@yottameta/yotta-humanize 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/CHANGELOG.md +10 -0
  2. package/README.md +84 -71
  3. package/README.zh-CN.md +159 -0
  4. package/SKILL.md +1 -1
  5. package/package.json +4 -3
  6. package/scripts/yotta_humanize.py +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,15 @@
1
1
  # 更新日志
2
2
 
3
+ ## v0.1.1 (2026-08-28)
4
+
5
+ 中英双语 README 对齐（老张拍板「英文门面 + 中文全档」）：
6
+
7
+ - **README.md 改为英文**：作为 GitHub / npm / ClawHub 首页的英文门面（翻译 + 精简，覆盖定位 / 核心价值 / 命令 / 快速使用 / 安装 / 使用示例 / 边界 / 开发校验全流程）。
8
+ - **新增 README.zh-CN.md**：原中文完整主文档整体平移，顶部加语言切换链接。
9
+ - **package.json**：description 改英文；files 加 README.zh-CN.md；版本 0.1.0 → 0.1.1。
10
+ - 版本四处对齐：package.json / SKILL frontmatter / 引擎 VERSION / 文档。
11
+ - 边界（B 方案）：references / CHANGELOG / 测试注释不翻译；SKILL 触发描述保持中文。
12
+
3
13
  ## v0.1.0 (2026-08-26)
4
14
 
5
15
  YottaMeta 自有实现首版（去 AI 味方向参考开源社区 humanizer / ai-humanizer 类技能思路，已完全重写为中文语料实现，零依赖、无上游代码）：
package/README.md CHANGED
@@ -1,13 +1,14 @@
1
+ <p align="center"><b>Language</b>: English · <a href="./README.zh-CN.md">中文</a></p>
1
2
 
2
3
  <p align="center">
3
4
  <img src="assets/banner.png" alt="yotta-humanize banner" width="100%" />
4
5
  </p>
5
6
 
6
- <h1 align="center">yotta-humanize · 元真</h1>
7
+ <h1 align="center">yotta-humanize · 元真 (Yuanzhen)</h1>
7
8
 
8
- <p align="center">YottaMeta 自有的去 AI 味中文写作编辑技能：<b>检测器引擎（24 类规则 + 词表 + 统计突发性）</b>识别 AI 腔文本，并给出确定性改写，让中文写作更自然、更像人写的。适用于编辑 / 润色文本、给 AI 生成的中文稿件做检测与改写。</p>
9
- <p align="center">检测到空泛升华、套话、AI 黑话（赋能 / 闭环 / 抓手）、同义堆叠、排比三连、聊天残渣（希望对你有所帮助）等 AI 腔特征时自动激活——<b>不靠提示词兜底，按规则确定性判定</b>。</p>
10
- <p align="center">纯 Python 3.8+ 标准库实现，零外部依赖；Windows + Linux + macOS 通用；检测 + 改写全流程，改写不依赖模型。</p>
9
+ <p align="center">YottaMeta's AI-flavor remover for Chinese writing: a <b>detector engine (24 rule classes + wordlists + statistical burstiness)</b> that identifies AI-typical text and applies <b>deterministic rewrites</b> to make Chinese copy read more naturally, more like a human wrote it. Use it to edit / polish text or to detect and rewrite AI-generated Chinese drafts.</p>
10
+ <p align="center">Activates when it detects AI-flavor patterns — empty uplift, clichés, AI jargon (赋能 / 闭环 / 抓手), synonym stacking, triple parallel constructions, chat residue (希望对你有所帮助) — <b>deterministic verdicts by rules, not prompt-engineering luck</b>.</p>
11
+ <p align="center">Pure Python 3.8+ standard library, zero external dependencies; Windows + Linux + macOS; detection + rewriting in one flow, rewriting does not depend on any model.</p>
11
12
 
12
13
  <p align="center">
13
14
  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue" /></a>
@@ -18,97 +19,97 @@
18
19
  <a href="https://github.com/YottaMeta/yotta-humanize"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen" /></a>
19
20
  </p>
20
21
 
21
- ## 这是什么
22
+ ## What it is
22
23
 
23
- AI 生成的中文文本有一眼可辨的「AI 腔」：空泛升华（标志着 / 彰显了）、套话（众所周知 / 综上所述 / 未来可期）、黑话（赋能 / 闭环 / 抓手 / 颗粒度）、机械列举（首先 / 其次 / 再次）、聊天残渣（希望对你有所帮助）……元真把这些特征做成**确定性检测器引擎**：24 类规则（词表 + 句式正则）+ 中文统计突发性（句长均匀度 / 词汇多样性），输出 0-100 的 AI 腔评分，并给出**确定性改写**（词表替换、套话删除、聊天残渣清理、标点限流）。
24
+ AI-generated Chinese text has a recognizable "AI flavor": empty uplift (标志着 / 彰显了), clichés (众所周知 / 综上所述 / 未来可期), jargon (赋能 / 闭环 / 抓手 / 颗粒度), mechanical enumeration (首先 / 其次 / 再次), chat residue (希望对你有所帮助)… Yuanzhen packages these signals into a **deterministic detector engine**: 24 rule classes (wordlists + sentence-pattern regexes) plus Chinese statistical burstiness (sentence-length uniformity / vocabulary diversity), outputting a 0-100 AI-flavor score and **deterministic rewrites** (wordlist substitution, cliché removal, chat-residue cleanup, punctuation throttling).
24
25
 
25
- 它不是某个平台的专属功能，而是一份与智能体无关的工具包：装进任何支持 Agent Skills 的智能体即可按需调用。全程零依赖、不调模型；需要判断的改写以建议形式给出，不强行自动改。
26
+ It is not tied to any single platform: an agent-agnostic toolkit that works in any agent supporting Agent Skills. Fully zero-dependency, no model calls; rewrites that need judgment are given as suggestions rather than forced automatically.
26
27
 
27
- ## 核心价值
28
+ ## Core value
28
29
 
29
- - **24 类检测规则**：内容（空泛升华 / 套话开头结尾 / 模糊归因 / 绝对化）/ 语言（AI 黑话 / 同义堆叠 / 名词化堆砌 / 「我们」滥用）/ 句式（排比三连 / 机械列举 / 反问堆叠 / 标点滥用）/ 沟通（聊天残渣 / 奉承讨好 / 免责回避）/ 废话（填充 / 转折 / 重复声明）。
30
- - **统计突发性**：句长均匀度（CV）、突发性、双字词汇多样性（TTR）、逗号密度——补规则检测不到的节奏问题。
31
- - **确定性改写**：无歧义机械变换直接改（赋能→支持、抓手→切入点、众所周知 / 综上所述 删除、希望对你有所帮助 清理、破折号 / 感叹号限流），输出修复清单与前后评分。
32
- - **机器可读**：--json 输出纯净 JSON；score --gate 接入 CI / 发布前检查。
33
- - **中文优先**：词表、句式、改写映射全部针对中文语料自研整理，与英文 humanizer 类技能无共享代码。
30
+ - **24 detection rule classes** — content (empty uplift / cliché openers-closers / vague attribution / absolutism), language (AI jargon / synonym stacking / noun pile-ups / "we" overuse), sentence style (triple parallel / mechanical enumeration / rhetorical-question piles / punctuation abuse), communication (chat residue / flattery / disclaimer avoidance), filler (padding / transitions / repeated statements).
31
+ - **Statistical burstiness** — sentence-length uniformity (CV), burstiness, two-character vocabulary diversity (TTR), comma density — catches rhythm problems rules cannot see.
32
+ - **Deterministic rewriting** — unambiguous mechanical transforms are applied directly (赋能→支持, 抓手→切入点, 众所周知 / 综上所述 deleted, 希望对你有所帮助 cleaned, dash / exclamation throttled), outputting a fix list and before/after scores.
33
+ - **Machine readable** — --json outputs pure JSON; score --gate plugs into CI / pre-release checks.
34
+ - **Chinese-first** — wordlists, sentence patterns and rewrite mappings are all curated for Chinese text; no shared code with English humanizer-style skills.
34
35
 
35
- ## 核心优势
36
+ ## Why use it
36
37
 
37
- | 优势 | 说明 |
38
+ | Advantage | Description |
38
39
  |---|---|
39
- | **零依赖** | Python 3.8+ 标准库，无模型、无数据库、无外部服务；Windows + Linux + macOS 通用 |
40
- | **确定性** | 规则判定可复现、可解释；改写是确定性变换，不依赖模型概率 |
41
- | **中文优先** | 针对中文 AI 腔（黑话 / 套话 / 排比 / 聊天残渣）自研词表与句式，非英文规则直译 |
42
- | **检测 + 改写一体** | score / analyze / report / suggest / rewrite 全流程，一条命令从检测到改写 |
43
- | **可复核** | 改写输出修复清单与前后评分，人工可逐条核对 |
44
- | **生态分发** | GitHub + npm + ClawHub 三源同步发布；npx / install.sh / 手动复制三种安装方式 |
40
+ | **Zero dependency** | Python 3.8+ standard library; no model / database / external service; Windows + Linux + macOS |
41
+ | **Deterministic** | Verdicts are reproducible and explainable; rewrites are deterministic transforms, not model probability |
42
+ | **Chinese-first** | Wordlists and patterns for Chinese AI-flavor (jargon / clichés / parallelism / chat residue) curated from scratch, not translated English rules |
43
+ | **Detect + rewrite in one** | score / analyze / report / suggest / rewrite — one command from detection to rewriting |
44
+ | **Reviewable** | Rewrites output a fix list and before/after scores so humans can verify item by item |
45
+ | **Ecosystem distribution** | GitHub + npm + ClawHub synced; install via npx / install.sh / manual copy |
45
46
 
46
- ## 功能体系
47
+ ## Commands
47
48
 
48
- | 能力 | 说明 |
49
+ | Command | Description |
49
50
  |---|---|
50
- | score | 输出 AI 腔评分（0-100），--gate 可做 CI 拦截（退出码 1） |
51
- | analyze | 详细检测报告（文本 / --json），含命中规则、上下文片段、建议 |
52
- | report | Markdown 检测报告（统计表 + 命中规则） |
53
- | suggest | 按优先级分组的改写建议 |
54
- | rewrite | 确定性改写：替换 / 删除 AI 腔，输出修复清单 + 改写后文本 + 前后评分 |
55
- | version | 打印版本 |
51
+ | score | AI-flavor score (0-100); --gate makes a CI gate (exit code 1) |
52
+ | analyze | Detailed detection report (text / --json) with matched rules, context snippets, suggestions |
53
+ | report | Markdown detection report (statistics table + matched rules) |
54
+ | suggest | Rewrite suggestions grouped by priority |
55
+ | rewrite | Deterministic rewrite: replace / remove AI-flavor, output fix list + rewritten text + before/after scores |
56
+ | version | Print the version |
56
57
 
57
- ## 快速使用
58
+ ## Quick start
58
59
 
59
- Windows 用 python，Linux/macOS 用 python3。
60
+ Windows uses python, Linux/macOS uses python3.
60
61
 
61
62
  ```bash
62
- # 评分（0-100，越高越像 AI 写的）
63
+ # Score (0-100, higher = more AI-like)
63
64
  python3 scripts/yotta_humanize.py score -f article.md
64
65
 
65
- # 详细检测报告
66
+ # Detailed detection report
66
67
  python3 scripts/yotta_humanize.py analyze -f article.md
67
68
 
68
- # Markdown 报告
69
+ # Markdown report
69
70
  python3 scripts/yotta_humanize.py report -f article.md > report.md
70
71
 
71
- # 按优先级分组的改写建议
72
+ # Rewrite suggestions grouped by priority
72
73
  python3 scripts/yotta_humanize.py suggest -f article.md
73
74
 
74
- # 确定性改写（输出改写后文本 + 修复清单）
75
+ # Deterministic rewrite (outputs rewritten text + fix list)
75
76
  python3 scripts/yotta_humanize.py rewrite -f article.md
76
77
 
77
- # 管道输入
78
+ # Pipe input
78
79
  cat article.md | python3 scripts/yotta_humanize.py score --stdin
79
80
 
80
- # CI 拦截：评分 >= 阈值时退出码 1
81
+ # CI gate: exit code 1 when score >= threshold
81
82
  python3 scripts/yotta_humanize.py score -f article.md --gate --threshold 45
82
83
  ```
83
84
 
84
- 退出码语义（与元安 / 元审 / 元盾家族一致）：0 = 成功；1 = score --gate 且评分达到阈值；4 = 用法错误 / 致命异常。
85
+ Exit codes (same semantics as the YuanAn / YuanShen / Yuandun family): **0** = success; **1** = score --gate and threshold reached; **4** = usage error / fatal exception.
85
86
 
86
- ## 安装
87
+ ## Install
87
88
 
88
- 三种方式任选其一，技能文件统一从 **npm** 获取（GitHub 无代理时较慢，npm 可配国内镜像加速）。
89
+ Pick any one of the three methods; skill files are fetched from **npm** (GitHub is slower without a proxy; npm can use a domestic mirror).
89
90
 
90
- ### 方式一：npm（推荐，一行安装）
91
+ ### Method 1: npm (recommended, one-liner)
91
92
  ```bash
92
- # 国内加速（可选）：npm config set registry https://registry.npmmirror.com
93
+ # domestic mirror (optional): npm config set registry https://registry.npmmirror.com
93
94
  npx -y @yottameta/yotta-humanize -g
94
- npx -y @yottameta/yotta-humanize --dir <你的技能目录> # 任意智能体：指定目录安装
95
+ npx -y @yottameta/yotta-humanize --dir <your-skills-dir> # any agent: install to a specific directory
95
96
  ```
96
- > 智能体不在预置列表里？用 --dir 指定它的 skills 目录，或手动复制（方式三）。--list 可查看各智能体对应的默认目录。想手动拿文件也可 npm pack @yottameta/yotta-humanize 解包后按方式二/三安装。
97
+ > Not in the preset list? Use --dir to point at the agent's skills directory, or manual copy (method 3). --list shows each agent's default directory. You can also npm pack @yottameta/yotta-humanize and unpack it to install via method 2 / 3.
97
98
 
98
- ### 方式二：install.sh 一键安装
99
- 获取技能文件夹后（npm pack 解包或 git clone），进入技能文件夹：
99
+ ### Method 2: install.sh one-shot
100
+ After obtaining the skill folder (npm pack unpack or git clone), enter the folder:
100
101
  ```bash
101
- bash install.sh -g # 用户级；bash install.sh --list 查看全部目录
102
- bash install.sh --agent codex # 指定智能体（--list 可查看可用项）
103
- bash install.sh # 项目级：自动检测已存在的 .claude/.cursor/.codex 等 skills 目录
102
+ bash install.sh -g # user level; bash install.sh --list shows all directories
103
+ bash install.sh --agent codex # specific agent (--list shows available ones)
104
+ bash install.sh # project level: auto-detect existing .claude/.cursor/.codex skills dirs
104
105
  bash install.sh --dir /path/to/skills
105
106
  ```
106
- > 覆盖 17 类智能体，含国内 Trae / Qwen / Comate / CodeBuddy / Kimi。Windows 用户：装有 Git Bash 即可用；否则用方式三手动复制。
107
+ > Covers 17 agent families including Trae / Qwen / Comate / CodeBuddy / Kimi. Windows users: works with Git Bash; otherwise use method 3.
107
108
 
108
- ### 方式三：手动复制
109
- 把整个 yotta-humanize 文件夹复制到目标智能体的 skills 目录。常见位置（用户级；Windows 用 %USERPROFILE%，Linux/macOS 用 ~）：
109
+ ### Method 3: manual copy
110
+ Copy the whole yotta-humanize folder into the target agent's skills directory. Common locations (user level; Windows uses %USERPROFILE%, Linux/macOS uses ~):
110
111
 
111
- | 智能体 | 用户级目录 | 项目级目录 |
112
+ | Agent | User-level directory | Project-level directory |
112
113
  |---|---|---|
113
114
  | Codex | %USERPROFILE%\.codex\skills\yotta-humanize\ | .codex\skills\ |
114
115
  | Claude Code | %USERPROFILE%\.claude\skills\yotta-humanize\ | .claude\skills\ |
@@ -121,37 +122,49 @@ bash install.sh --dir /path/to/skills
121
122
  | Kiro | %USERPROFILE%\.kiro\skills\yotta-humanize\ | .kiro\skills\ |
122
123
  | WorkBuddy | %USERPROFILE%\.workbuddy\skills\yotta-humanize\ | .workbuddy\skills\ |
123
124
  | Trae Code CLI | %USERPROFILE%\.traecli\skills\yotta-humanize\ | .traecli\skills\ |
124
- | Trae IDE（国内） | %USERPROFILE%\.trae-cn\skills\yotta-humanize\ | .trae\skills\ |
125
+ | Trae IDE (CN) | %USERPROFILE%\.trae-cn\skills\yotta-humanize\ | .trae\skills\ |
125
126
  | Qwen Code | %USERPROFILE%\.qwen\skills\yotta-humanize\ | .qwen\skills\ |
126
127
  | Comate | %USERPROFILE%\.comate\skills\yotta-humanize\ | .comate\skills\ |
127
128
  | CodeBuddy | %USERPROFILE%\.codebuddy\skills\yotta-humanize\ | .codebuddy\skills\ |
128
129
  | Kimi | %USERPROFILE%\.kimi\skills\yotta-humanize\ | .kimi\skills\ |
129
- | 通用 AGENTS.md | %USERPROFILE%\.agents\skills\yotta-humanize\ | .agents\skills\ |
130
+ | Generic AGENTS.md | %USERPROFILE%\.agents\skills\yotta-humanize\ | .agents\skills\ |
130
131
 
131
- > Codex 默认目录若设置了环境变量 CODEX_HOME，以该变量为准；opencode 若设置 XDG_CONFIG_HOME 同理。.agents\skills 并非通用目录，仅 OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot 等会读取，Claude Code 与 Codex 默认不读。不确定时用 --dir 指定，或让该智能体自行安装。
132
+ > If Codex's CODEX_HOME is set, it overrides the default; the same applies to opencode's XDG_CONFIG_HOME. .agents\skills is not a universal directory — only OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot etc. read it; **Claude Code and Codex do not read it by default**. When unsure, use --dir or let the agent install it.
132
133
 
133
- ## 使用示例（AI 智能体）
134
+ ## Usage examples (AI agent)
134
135
 
135
- 1. 将本仓库的 SKILL.md 接入任意 AI 智能体的技能/规则系统（见上方安装）。
136
- 2. 收到一段 AI 味很重的文稿时，先跑一次检测：
136
+ 1. Hook this repo's SKILL.md into any AI agent's skill/rule system (see install above).
137
+ 2. When you receive a heavily AI-flavored draft, run a detection first:
137
138
  ```bash
138
139
  python3 scripts/yotta_humanize.py analyze -f draft.md
139
140
  ```
140
- 看评分与命中规则（空泛升华 / 黑话 / 套话 / 聊天残渣等）。
141
- 3. 无歧义的部分直接机械改写：
141
+ Check the score and matched rules (empty uplift / jargon / clichés / chat residue, etc.).
142
+ 3. Apply direct mechanical rewrites for the unambiguous parts:
142
143
  ```bash
143
144
  python3 scripts/yotta_humanize.py rewrite -f draft.md
144
145
  ```
145
- 对照修复清单确认，把改写后文本落回稿件。
146
- 4. 需要判断的部分（排比拆句、模糊归因补来源、绝对化软化）按 suggest 的建议手工润色。
147
- 5. 改写完再 score 一次，确认评分下降、原意未破坏。
146
+ Review against the fix list and write the rewritten text back into the draft.
147
+ 4. For parts that need judgment (splitting parallel constructions, adding sources for vague attribution, softening absolutism), polish by hand following the suggest output.
148
+ 5. After rewriting, score once more to confirm the score dropped and the original meaning is intact.
148
149
 
149
- ## 开发与校验
150
+ ## Boundaries
150
151
 
151
- - 测试：python scripts/test_yotta_humanize.py（155 项）
152
- - 基础校验：python tools/validate-skill.py yotta-humanize（在仓库根目录运行）
153
- - 规则目录：references/patterns.md；评分公式：references/scoring.md；改写规则：references/rewriting.md
152
+ - **Text-only, no generation** — it edits existing text; it does not create new content, and it does not alter facts / data / proper nouns against the author's intent.
153
+ - **Rewrites are suggestions** — unambiguous transforms apply directly; judgment-heavy rewrites are listed as suggestions for the human to confirm.
154
+ - **No model dependency** — deterministic rules only; results are reproducible and explainable.
154
155
 
155
- ## 许可证
156
+ ## Development & validation
156
157
 
157
- MIT © YottaMeta —— 详见 [LICENSE](./LICENSE)。
158
+ - Tests: python scripts/test_yotta_humanize.py (155 tests; Windows: python)
159
+ - Base validation: python tools/validate-skill.py yotta-humanize (run at the repo root)
160
+ - Rule catalog: references/patterns.md; scoring formula: references/scoring.md; rewriting rules: references/rewriting.md
161
+
162
+ Keep tests green and bump the version before releasing changes.
163
+
164
+ ## Changelog
165
+
166
+ See [CHANGELOG.md](./CHANGELOG.md).
167
+
168
+ ## License
169
+
170
+ [MIT](./LICENSE) © YottaMeta. "Yuanzhen" / "yotta-humanize" and the YottaMeta family names (yotta-* prefix) are YottaMeta brand identifiers; derived works must not reuse them, see [NOTICE](./NOTICE). The de-AI-flavor direction references open-source humanizer-style skills; the implementation is YottaMeta's own Chinese-corpus code.
package/README.zh-CN.md ADDED
@@ -0,0 +1,159 @@
1
+ <p align="center"><b>Language</b>: <a href="./README.md">English</a> · 中文</p>
2
+
3
+
4
+ <p align="center">
5
+ <img src="assets/banner.png" alt="yotta-humanize banner" width="100%" />
6
+ </p>
7
+
8
+ <h1 align="center">yotta-humanize · 元真</h1>
9
+
10
+ <p align="center">YottaMeta 自有的去 AI 味中文写作编辑技能：<b>检测器引擎（24 类规则 + 词表 + 统计突发性）</b>识别 AI 腔文本，并给出确定性改写，让中文写作更自然、更像人写的。适用于编辑 / 润色文本、给 AI 生成的中文稿件做检测与改写。</p>
11
+ <p align="center">检测到空泛升华、套话、AI 黑话（赋能 / 闭环 / 抓手）、同义堆叠、排比三连、聊天残渣（希望对你有所帮助）等 AI 腔特征时自动激活——<b>不靠提示词兜底，按规则确定性判定</b>。</p>
12
+ <p align="center">纯 Python 3.8+ 标准库实现，零外部依赖；Windows + Linux + macOS 通用；检测 + 改写全流程，改写不依赖模型。</p>
13
+
14
+ <p align="center">
15
+ <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue" /></a>
16
+ <a href="https://agentskills.io/"><img alt="Standard: agentskills.io" src="https://img.shields.io/badge/standard-agentskills.io-orange" /></a>
17
+ <a href="https://www.npmjs.com/package/@yottameta/yotta-humanize"><img alt="npm package" src="https://img.shields.io/npm/v/@yottameta/yotta-humanize" /></a>
18
+ <a href="https://github.com/YottaMeta/yotta-humanize"><img alt="GitHub stars" src="https://img.shields.io/github/stars/YottaMeta/yotta-humanize" /></a>
19
+ <a href="https://github.com/YottaMeta/yotta-humanize/commits/main"><img alt="last commit" src="https://img.shields.io/github/last-commit/YottaMeta/yotta-humanize" /></a>
20
+ <a href="https://github.com/YottaMeta/yotta-humanize"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen" /></a>
21
+ </p>
22
+
23
+ ## 这是什么
24
+
25
+ AI 生成的中文文本有一眼可辨的「AI 腔」：空泛升华（标志着 / 彰显了）、套话（众所周知 / 综上所述 / 未来可期）、黑话（赋能 / 闭环 / 抓手 / 颗粒度）、机械列举（首先 / 其次 / 再次）、聊天残渣（希望对你有所帮助）……元真把这些特征做成**确定性检测器引擎**：24 类规则（词表 + 句式正则）+ 中文统计突发性（句长均匀度 / 词汇多样性），输出 0-100 的 AI 腔评分，并给出**确定性改写**（词表替换、套话删除、聊天残渣清理、标点限流）。
26
+
27
+ 它不是某个平台的专属功能，而是一份与智能体无关的工具包：装进任何支持 Agent Skills 的智能体即可按需调用。全程零依赖、不调模型；需要判断的改写以建议形式给出，不强行自动改。
28
+
29
+ ## 核心价值
30
+
31
+ - **24 类检测规则**：内容（空泛升华 / 套话开头结尾 / 模糊归因 / 绝对化）/ 语言（AI 黑话 / 同义堆叠 / 名词化堆砌 / 「我们」滥用）/ 句式（排比三连 / 机械列举 / 反问堆叠 / 标点滥用）/ 沟通（聊天残渣 / 奉承讨好 / 免责回避）/ 废话（填充 / 转折 / 重复声明）。
32
+ - **统计突发性**：句长均匀度（CV）、突发性、双字词汇多样性（TTR）、逗号密度——补规则检测不到的节奏问题。
33
+ - **确定性改写**：无歧义机械变换直接改（赋能→支持、抓手→切入点、众所周知 / 综上所述 删除、希望对你有所帮助 清理、破折号 / 感叹号限流），输出修复清单与前后评分。
34
+ - **机器可读**：--json 输出纯净 JSON；score --gate 接入 CI / 发布前检查。
35
+ - **中文优先**：词表、句式、改写映射全部针对中文语料自研整理，与英文 humanizer 类技能无共享代码。
36
+
37
+ ## 核心优势
38
+
39
+ | 优势 | 说明 |
40
+ |---|---|
41
+ | **零依赖** | Python 3.8+ 标准库，无模型、无数据库、无外部服务；Windows + Linux + macOS 通用 |
42
+ | **确定性** | 规则判定可复现、可解释；改写是确定性变换，不依赖模型概率 |
43
+ | **中文优先** | 针对中文 AI 腔（黑话 / 套话 / 排比 / 聊天残渣）自研词表与句式，非英文规则直译 |
44
+ | **检测 + 改写一体** | score / analyze / report / suggest / rewrite 全流程，一条命令从检测到改写 |
45
+ | **可复核** | 改写输出修复清单与前后评分，人工可逐条核对 |
46
+ | **生态分发** | GitHub + npm + ClawHub 三源同步发布；npx / install.sh / 手动复制三种安装方式 |
47
+
48
+ ## 功能体系
49
+
50
+ | 能力 | 说明 |
51
+ |---|---|
52
+ | score | 输出 AI 腔评分（0-100），--gate 可做 CI 拦截（退出码 1） |
53
+ | analyze | 详细检测报告（文本 / --json），含命中规则、上下文片段、建议 |
54
+ | report | Markdown 检测报告（统计表 + 命中规则） |
55
+ | suggest | 按优先级分组的改写建议 |
56
+ | rewrite | 确定性改写：替换 / 删除 AI 腔，输出修复清单 + 改写后文本 + 前后评分 |
57
+ | version | 打印版本 |
58
+
59
+ ## 快速使用
60
+
61
+ Windows 用 python，Linux/macOS 用 python3。
62
+
63
+ ```bash
64
+ # 评分（0-100，越高越像 AI 写的）
65
+ python3 scripts/yotta_humanize.py score -f article.md
66
+
67
+ # 详细检测报告
68
+ python3 scripts/yotta_humanize.py analyze -f article.md
69
+
70
+ # Markdown 报告
71
+ python3 scripts/yotta_humanize.py report -f article.md > report.md
72
+
73
+ # 按优先级分组的改写建议
74
+ python3 scripts/yotta_humanize.py suggest -f article.md
75
+
76
+ # 确定性改写（输出改写后文本 + 修复清单）
77
+ python3 scripts/yotta_humanize.py rewrite -f article.md
78
+
79
+ # 管道输入
80
+ cat article.md | python3 scripts/yotta_humanize.py score --stdin
81
+
82
+ # CI 拦截：评分 >= 阈值时退出码 1
83
+ python3 scripts/yotta_humanize.py score -f article.md --gate --threshold 45
84
+ ```
85
+
86
+ 退出码语义（与元安 / 元审 / 元盾家族一致）：0 = 成功；1 = score --gate 且评分达到阈值；4 = 用法错误 / 致命异常。
87
+
88
+ ## 安装
89
+
90
+ 三种方式任选其一，技能文件统一从 **npm** 获取（GitHub 无代理时较慢，npm 可配国内镜像加速）。
91
+
92
+ ### 方式一：npm（推荐，一行安装）
93
+ ```bash
94
+ # 国内加速（可选）：npm config set registry https://registry.npmmirror.com
95
+ npx -y @yottameta/yotta-humanize -g
96
+ npx -y @yottameta/yotta-humanize --dir <你的技能目录> # 任意智能体：指定目录安装
97
+ ```
98
+ > 智能体不在预置列表里？用 --dir 指定它的 skills 目录，或手动复制（方式三）。--list 可查看各智能体对应的默认目录。想手动拿文件也可 npm pack @yottameta/yotta-humanize 解包后按方式二/三安装。
99
+
100
+ ### 方式二：install.sh 一键安装
101
+ 获取技能文件夹后（npm pack 解包或 git clone），进入技能文件夹：
102
+ ```bash
103
+ bash install.sh -g # 用户级；bash install.sh --list 查看全部目录
104
+ bash install.sh --agent codex # 指定智能体（--list 可查看可用项）
105
+ bash install.sh # 项目级：自动检测已存在的 .claude/.cursor/.codex 等 skills 目录
106
+ bash install.sh --dir /path/to/skills
107
+ ```
108
+ > 覆盖 17 类智能体，含国内 Trae / Qwen / Comate / CodeBuddy / Kimi。Windows 用户：装有 Git Bash 即可用；否则用方式三手动复制。
109
+
110
+ ### 方式三：手动复制
111
+ 把整个 yotta-humanize 文件夹复制到目标智能体的 skills 目录。常见位置（用户级；Windows 用 %USERPROFILE%，Linux/macOS 用 ~）：
112
+
113
+ | 智能体 | 用户级目录 | 项目级目录 |
114
+ |---|---|---|
115
+ | Codex | %USERPROFILE%\.codex\skills\yotta-humanize\ | .codex\skills\ |
116
+ | Claude Code | %USERPROFILE%\.claude\skills\yotta-humanize\ | .claude\skills\ |
117
+ | Cursor | %USERPROFILE%\.cursor\skills\yotta-humanize\ | .cursor\skills\ |
118
+ | Windsurf | %USERPROFILE%\.codeium\windsurf\skills\yotta-humanize\ | .windsurf\skills\ |
119
+ | opencode | %USERPROFILE%\.config\opencode\skills\yotta-humanize\ | .opencode\skills\ |
120
+ | Gemini | %USERPROFILE%\.gemini\skills\yotta-humanize\ | .gemini\skills\ |
121
+ | Goose | %USERPROFILE%\.config\goose\skills\yotta-humanize\ | .goose\skills\ |
122
+ | Amp | %USERPROFILE%\.config\agents\skills\yotta-humanize\ | .agents\skills\ |
123
+ | Kiro | %USERPROFILE%\.kiro\skills\yotta-humanize\ | .kiro\skills\ |
124
+ | WorkBuddy | %USERPROFILE%\.workbuddy\skills\yotta-humanize\ | .workbuddy\skills\ |
125
+ | Trae Code CLI | %USERPROFILE%\.traecli\skills\yotta-humanize\ | .traecli\skills\ |
126
+ | Trae IDE（国内） | %USERPROFILE%\.trae-cn\skills\yotta-humanize\ | .trae\skills\ |
127
+ | Qwen Code | %USERPROFILE%\.qwen\skills\yotta-humanize\ | .qwen\skills\ |
128
+ | Comate | %USERPROFILE%\.comate\skills\yotta-humanize\ | .comate\skills\ |
129
+ | CodeBuddy | %USERPROFILE%\.codebuddy\skills\yotta-humanize\ | .codebuddy\skills\ |
130
+ | Kimi | %USERPROFILE%\.kimi\skills\yotta-humanize\ | .kimi\skills\ |
131
+ | 通用 AGENTS.md | %USERPROFILE%\.agents\skills\yotta-humanize\ | .agents\skills\ |
132
+
133
+ > Codex 默认目录若设置了环境变量 CODEX_HOME，以该变量为准；opencode 若设置 XDG_CONFIG_HOME 同理。.agents\skills 并非通用目录，仅 OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot 等会读取，Claude Code 与 Codex 默认不读。不确定时用 --dir 指定，或让该智能体自行安装。
134
+
135
+ ## 使用示例（AI 智能体）
136
+
137
+ 1. 将本仓库的 SKILL.md 接入任意 AI 智能体的技能/规则系统（见上方安装）。
138
+ 2. 收到一段 AI 味很重的文稿时，先跑一次检测：
139
+ ```bash
140
+ python3 scripts/yotta_humanize.py analyze -f draft.md
141
+ ```
142
+ 看评分与命中规则（空泛升华 / 黑话 / 套话 / 聊天残渣等）。
143
+ 3. 无歧义的部分直接机械改写：
144
+ ```bash
145
+ python3 scripts/yotta_humanize.py rewrite -f draft.md
146
+ ```
147
+ 对照修复清单确认，把改写后文本落回稿件。
148
+ 4. 需要判断的部分（排比拆句、模糊归因补来源、绝对化软化）按 suggest 的建议手工润色。
149
+ 5. 改写完再 score 一次，确认评分下降、原意未破坏。
150
+
151
+ ## 开发与校验
152
+
153
+ - 测试：python scripts/test_yotta_humanize.py（155 项）
154
+ - 基础校验：python tools/validate-skill.py yotta-humanize（在仓库根目录运行）
155
+ - 规则目录：references/patterns.md；评分公式：references/scoring.md；改写规则：references/rewriting.md
156
+
157
+ ## 许可证
158
+
159
+ MIT © YottaMeta —— 详见 [LICENSE](./LICENSE)。
package/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: yotta-humanize
3
- version: 0.1.0
3
+ version: 0.1.1
4
4
  description: 元真 —— 去 AI 味的中文写作编辑技能：检测器引擎（24 类规则 + 词表 + 统计突发性）识别并改写 AI 腔文本，让中文写作更自然、更像人写的。触发：编辑 / 润色文本、去 AI 味、让文章 / 文案 / 回复更像人写、发现文本充斥着 AI 常用词与句式（赋能 / 闭环 / 值得注意的是 / 综上所述 / 希望对你有所帮助 等）、给 AI 生成的中文稿件做检测与改写。边界：只处理文本，不生成新内容；不改写事实 / 数据 / 专有名词；不破坏作者原意；改写为确定性规则，不依赖模型。
5
5
  license: MIT
6
6
  ---
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@yottameta/yotta-humanize",
3
- "version": "0.1.0",
4
- "description": "元真 —— 去 AI 味的中文写作编辑技能：检测器引擎（24 类 + 词表 + 统计突发性）识别并改写 AI 腔文本，让中文写作更自然。触发：编辑/润色文本、去掉 AI 味、让文案更像人写时。边界：只处理文本，不生成新内容。",
3
+ "version": "0.1.1",
4
+ "description": "Yuanzhen (元真) — AI-flavor remover for Chinese writing: a detector engine (24 rule classes + wordlists + statistical burstiness) that identifies and rewrites AI-typical Chinese text to make it read more naturally. Triggers when editing/polishing text, removing AI flavor, or making copy read more human. Boundaries: text-only, deterministic rewrites, no model dependency.",
5
5
  "license": "MIT",
6
6
  "keywords": [
7
7
  "agent-skills",
@@ -17,7 +17,8 @@
17
17
  "assets",
18
18
  "bin",
19
19
  "NOTICE",
20
- "CHANGELOG.md"
20
+ "CHANGELOG.md",
21
+ "README.zh-CN.md"
21
22
  ],
22
23
  "repository": {
23
24
  "type": "git",
package/scripts/yotta_humanize.py CHANGED
@@ -47,7 +47,7 @@ _HERE = Path(__file__).resolve().parent
47
47
  sys.path.insert(0, str(_HERE))
48
48
  import humanize_rules as HR # noqa: E402
49
49
 
50
- VERSION = "0.1.0"
50
+ VERSION = "0.1.1"
51
51
  TOOL_NAME = "yotta-humanize"
52
52
  TOOL_CN = "元真"
53
53
  DEFAULT_THRESHOLD = 45