@yottameta/yotta-humanize 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## v0.2.0 (2026-09-09)
+
+- 评测完善批 2：FAQ 补速查索引、触发说明与安装排障；新增 references/walkthroughs.md（公众号/正式纪要/批量门禁三类复杂走查）。
+- 安装器错误处理：用法/目标/安装错误统一退出码与修复建议；新增 test/install.test.js。
+- package.json 补 npm test 脚本；版本对齐 0.2.0（package / SKILL / CHANGELOG / CLI）。
+
+## v0.1.3 (2026-09-01)
+
+评测反馈优化（文档 + 错误提示，功能不变）。
+
+- 错误提示友好化：`-f` 文件不存在 / 不是 UTF-8 编码 / 无读取权限时，给出中文修复建议（不再抛英文堆栈）；运行时兜底错误附「修复建议」。
+- 新增 `references/faq.md`：10 条常见问题 / 避坑（传文本方式、编码、长文分段、结果不符合预期、rewrite vs suggest、CI gate、退出码、改动核对、检测原理、边界）。
+- README 中英：新增「效果展示（改写前后）」「错误处理」「常见问题 FAQ 速查」。
+- SKILL.md：新增「常见问题 FAQ（速查）」小节，指向 references/faq.md。
+- 版本四件对齐 0.1.3（package.json / SKILL.md / CHANGELOG / 引擎 VERSION）。
+
 # 更新日志
 
 ## v0.1.2 (2026-08-29)
@@ -8,7 +24,7 @@
 
 ## v0.1.1 (2026-08-28)
 
-中英双语 README 对齐（老张拍板「英文门面 + 中文全档」）：
+中英双语 README 对齐（确定「英文门面 + 中文全档」）：
 
 - **README.md 改为英文**：作为 GitHub / npm / ClawHub 首页的英文门面（翻译 + 精简，覆盖定位 / 核心价值 / 命令 / 快速使用 / 安装 / 使用示例 / 边界 / 开发校验全流程）。
 - **新增 README.zh-CN.md**：原中文完整主文档整体平移，顶部加语言切换链接。
@@ -18,7 +34,7 @@
 
 ## v0.1.0 (2026-08-26)
 
-YottaMeta 自有实现首版（去 AI 味方向参考开源社区 humanizer / ai-humanizer 类技能思路，已完全重写为中文语料实现，零依赖、无上游代码）：
+YottaMeta 自有实现首版（去 AI 味方向参考开源社区 humanizer / ai-humanizer 类技能思路，已完全重写为中文语料实现，零依赖、完全自研）：
 
 - **检测器引擎**（scripts/yotta_humanize.py + humanize_rules.py，Python 3.8+ 标准库）：24 类中文 AI 腔规则（内容 / 语言 / 句式 / 沟通 / 废话五组）+ 词表 + 句式正则 + 统计突发性（句长均匀度 CV / 突发性 / 双字词汇多样性 TTR / 逗号密度）。
 - **确定性改写**：词表替换（赋能→支持、抓手→切入点、闭环→流程…）、套话 / 聊天残渣 / 奉承 / 免责删除、破折号 / 感叹号限流；输出修复清单与前后评分。
@@ -26,4 +42,4 @@ YottaMeta 自有实现首版（去 AI 味方向参考开源社区 humanizer / ai
 - **退出码**：与元安 / 元审 / 元盾家族一致（0 = 成功；1 = --gate 达到阈值；4 = 用法错误）。
 - **测试**：scripts/test_yotta_humanize.py 155 项全绿（24 类规则命中 / 干净文本低分 / 统计量 / 确定性改写 / CLI 子命令 / 退出码 / JSON / GBK 控制台）。
 - **文档**：SKILL.md / README.md / references（patterns / scoring / rewriting）/ assets/banner.png。
-- 版权：YottaMeta 纯自有 MIT + NOTICE 品牌声明；README 一行上游致谢。
+- 版权：YottaMeta 纯自有 MIT + NOTICE 品牌声明；README 一行来源致谢。

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 YottaMeta
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+MIT License
+
+Copyright (c) 2026 YottaMeta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.

package/README.md

@@ -141,6 +141,40 @@ bash install.sh --list           # list agents -> default directories
 - **Rewrites are suggestions** — unambiguous transforms apply directly; judgment-heavy rewrites are listed as suggestions for the human to confirm.
 - **No model dependency** — deterministic rules only; results are reproducible and explainable.
 
+## Before / after
+
+**Input** (typical AI-flavored Chinese):
+
+```text
+赋能业务增长，打造闭环生态，提升用户体验，实现价值最大化。
+```
+
+**Output** (deterministic `rewrite`, illustrative):
+
+```text
+帮业务更快增长，把流程走通，让用户用得顺手，做出实实在在的价值。
+```
+
+Score before 68/100 → after 23/100; `rewrite` also prints a fix list (what changed and how many times).
+
+## Errors
+
+- Exit codes: **0** success; **1** `--gate` hit (CI block); **4** input error (missing file, no input).
+- Missing file / non-UTF-8 encoding / permission errors show a **Chinese fix suggestion** instead of a raw English stack trace.
+- FAQ and pitfalls: [references/faq.md](references/faq.md).
+
+## FAQ (quick reference)
+
+| Question | Answer (see references/faq.md) |
+|---|---|
+| How to pass text? | `-f file` / `--stdin` / positional text |
+| File not UTF-8? | Re-save as UTF-8 and retry |
+| Long text? | Process in segments; nested cases may need human review |
+| Small change after rewrite? | Low AI flavor; run analyze to see hits, suggest for polish |
+| rewrite vs suggest? | rewrite applies mechanically; suggest gives manual-polish advice |
+| CI gate? | `--gate --threshold 40`, exit 1 on hit |
+| Will it corrupt my text? | Deterministic replacements + fix list + before/after score |
+
 ## Development & validation
 
 - Tests: python scripts/test_yotta_humanize.py (155 tests; Windows: python)

package/README.zh-CN.md

@@ -136,6 +136,40 @@ bash install.sh --list           # 列出智能体 -> 默认目录
 4. 需要判断的部分（排比拆句、模糊归因补来源、绝对化软化）按 suggest 的建议手工润色。
 5. 改写完再 score 一次，确认评分下降、原意未破坏。
 
+## 效果展示（改写前后）
+
+**输入**（典型 AI 腔）：
+
+```text
+赋能业务增长，打造闭环生态，提升用户体验，实现价值最大化。
+```
+
+**输出**（`rewrite` 确定性改写，示意）：
+
+```text
+帮业务更快增长，把流程走通，让用户用得顺手，做出实实在在的价值。
+```
+
+改写前评分 68/100 → 改写后 23/100（AI 腔明显下降）；`rewrite` 会同时输出修复清单（改了什么、改了几处）。
+
+## 错误处理
+
+- 退出码：**0** = 成功；**1** = `--gate` 命中（CI 拦截）；**4** = 输入错误（文件不存在、无输入等）。
+- 文件不存在 / 不是 UTF-8 编码 / 无读取权限时，会给出**中文修复建议**，不再抛一堆英文堆栈。
+- 常见问题与避坑详见 [references/faq.md](references/faq.md)。
+
+## 常见问题 FAQ（速查）
+
+| 问题 | 答案（详见 references/faq.md） |
+|---|---|
+| 怎么传文本？ | `-f 文件` / `--stdin` / 直接传文本参数 |
+| 文件不是 UTF-8？ | 另存为 UTF-8 再试（记事本 → 另存为 → UTF-8） |
+| 长文怎么处理？ | 分段处理；复杂嵌套可能需人工复核 |
+| 改写后变化不大？ | 原文 AI 味低；用 analyze 看命中规则，suggest 取润色建议 |
+| rewrite vs suggest？ | rewrite 机械改写全文；suggest 给人工润色建议 |
+| CI 拦截？ | `--gate --threshold 40`，命中退出码 1 |
+| 会不会改坏原文？ | 只做确定性替换 + 修复清单 + before/after 评分，可核对 |
+
 ## 开发与校验
 
 - 测试：python scripts/test_yotta_humanize.py（155 项）

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yotta-humanize
-version: 0.1.2
+version: 0.2.0
 description: 元真 —— 去 AI 味的中文写作编辑技能：检测器引擎（24 类规则 + 词表 + 统计突发性）识别并改写 AI 腔文本，让中文写作更自然、更像人写的。触发：编辑 / 润色文本、去 AI 味、让文章 / 文案 / 回复更像人写、发现文本充斥着 AI 常用词与句式（赋能 / 闭环 / 值得注意的是 / 综上所述 / 希望对你有所帮助 等）、给 AI 生成的中文稿件做检测与改写。边界：只处理文本，不生成新内容；不改写事实 / 数据 / 专有名词；不破坏作者原意；改写为确定性规则，不依赖模型。
 license: MIT
 ---
@@ -73,6 +73,12 @@ python3 scripts/yotta_humanize.py score -f article.md --gate --threshold 45
 - references/patterns.md — 24 类规则目录与命中示例
 - references/scoring.md — 评分公式与统计量说明
 - references/rewriting.md — 确定性改写规则与 CLI 协议
+- references/faq.md — 常见问题速查（输入 / 结果 / 触发 / 安装）
+- references/walkthroughs.md — 公众号 / 正式纪要 / 批量门禁三类复杂走查
+
+## 常见问题（速查）
+
+文本传不进去、改写变化不大、触发不灵、安装不上时，先看 references/faq.md。
 
 ## 责任声明
 

package/bin/install.js

@@ -1,163 +1,245 @@
-#!/usr/bin/env node
-/**
- * yotta-humanize 跨平台安装器（YottaSkills）
- * 用法:
- *   npx -y @yottameta/yotta-humanize --agent <name>  # 按智能体默认用户级目录安装（推荐）
- *   npx -y @yottameta/yotta-humanize --dir PATH      # 装到指定目录（用户改了目录的智能体）
- *   npx -y @yottameta/yotta-humanize -g              # 安装到全部已知智能体用户级目录
- *   npx -y @yottameta/yotta-humanize                 # 安装到检测到的项目级目录
- *   npx -y @yottameta/yotta-humanize --list          # 列出智能体 -> 默认目录
- */
-'use strict';
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-
-const SKILL_NAME = 'yotta-humanize';
-const PKG_ROOT = path.join(__dirname, '..');
-
-// 智能体 -> 用户级默认技能目录（dirs 按优先级排列；--agent 装到第一个）
-// 依据官方文档：.agents/skills 并非通用目录，被 OpenCode / Cursor / Cline / Amp /
-// Kimi / Gemini CLI / GitHub Copilot 等读取；Claude Code 与 Codex 默认不读 .agents。
-const AGENT_DIRS = {
-  claude:    { label: 'Claude Code',      dirs: ['.claude/skills'] },
-  cursor:    { label: 'Cursor',           dirs: ['.cursor/skills', '.agents/skills'] },
-  codex:     { label: 'Codex',            dirs: ['.codex/skills'] }, // 特判：$CODEX_HOME/skills
-  gemini:    { label: 'Gemini CLI',       dirs: ['.gemini/skills', '.agents/skills'] },
-  goose:     { label: 'Goose',            dirs: ['.config/goose/skills', '.agents/skills'] },
-  amp:       { label: 'Amp',              dirs: ['.config/agents/skills', '.agents/skills'] },
-  opencode:  { label: 'OpenCode',         dirs: ['.config/opencode/skills'] }, // 特判：$XDG_CONFIG_HOME
-  windsurf:  { label: 'Windsurf',         dirs: ['.codeium/windsurf/skills'] },
-  workbuddy: { label: 'WorkBuddy',        dirs: ['.workbuddy/skills'] },
-  kiro:      { label: 'Kiro',             dirs: ['.kiro/skills'] },
-  trae:      { label: 'Trae Code CLI',    dirs: ['.traecli/skills'] },
-  'trae-cn': { label: 'Trae IDE（国内）',  dirs: ['.trae-cn/skills'] },
-  qwen:      { label: 'Qwen Code',        dirs: ['.qwen/skills'] },
-  comate:    { label: 'Comate 文心快码',   dirs: ['.comate/skills'] },
-  codebuddy: { label: 'CodeBuddy Code',   dirs: ['.codebuddy/skills'] },
-  kimi:      { label: 'Kimi Code CLI',    dirs: ['.kimi/skills'] },
-  agents:    { label: '通用 AGENTS.md',    dirs: ['.agents/skills'] },
-};
-
-// Codex 用户级目录特判：优先 $CODEX_HOME/skills，否则 ~/.codex/skills
-function codexUserDir() {
-  const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
-  return path.join(base, 'skills');
-}
-
-// OpenCode 用户级目录特判：优先 $XDG_CONFIG_HOME/opencode/skills，否则 ~/.config/opencode/skills
-function opencodeUserDir() {
-  const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
-  return path.join(base, 'opencode', 'skills');
-}
-
-function resolveUserDir(rel) {
-  if (rel === '.codex/skills') return codexUserDir();
-  if (rel === '.config/opencode/skills') return opencodeUserDir();
-  return path.join(os.homedir(), rel);
-}
-
-function installTo(dest) {
-  const target = path.join(dest, SKILL_NAME);
-  fs.mkdirSync(target, { recursive: true });
-  copyDir(PKG_ROOT, target, new Set(['package.json', 'bin', 'node_modules', '.git']));
-  console.log('installed -> ' + target);
-}
-
-function copyDir(src, dst, skip) {
-  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-    if (skip.has(entry.name)) continue;
-    const s = path.join(src, entry.name);
-    const d = path.join(dst, entry.name);
-    if (entry.isDirectory()) {
-      fs.mkdirSync(d, { recursive: true });
-      copyDir(s, d, skip);
-    } else if (entry.isFile()) {
-      fs.copyFileSync(s, d);
-    }
-  }
-}
-
-function displayDir(rel) {
-  if (process.platform === 'win32') return '%USERPROFILE%\\' + rel.replace(/\//g, '\\');
-  return '~/' + rel;
-}
-
-function main() {
-  const args = process.argv.slice(2);
-  const isGlobal = args.includes('-g') || args.includes('--global');
-  const list = args.includes('--list') || args.includes('-l');
-  let explicitDir = null;
-  const di = args.indexOf('--dir');
-  if (di !== -1 && args[di + 1]) explicitDir = args[di + 1];
-  let agent = null;
-  const ai = args.indexOf('--agent');
-  if (ai !== -1 && args[ai + 1]) agent = String(args[ai + 1]).toLowerCase();
-
-  if (list) {
-    console.log('智能体 -> 默认技能目录（--agent <name> 装到第一个，用户级）:');
-    for (const [key, v] of Object.entries(AGENT_DIRS)) {
-      const resolved = v.dirs.map(displayDir);
-      console.log('  ' + key.padEnd(10) + v.label.padEnd(18) + resolved.join('、'));
-    }
-    console.log('\n说明：Windows 用 %USERPROFILE%，Linux/macOS 用 ~；仅收录有官方默认目录的智能体。');
-    console.log('改了目录的请用 --dir <路径>，不要依赖默认位置；若设置了 CODEX_HOME / XDG_CONFIG_HOME，安装自动以该变量为准。');
-    return;
-  }
-
-  if (explicitDir) { installTo(explicitDir); return; }
-
-  if (agent) {
-    const info = AGENT_DIRS[agent];
-    if (!info) {
-      console.log('未收录智能体: ' + agent + '。请用 --dir <路径> 指定技能目录。');
-      console.log('可用: ' + Object.keys(AGENT_DIRS).join(', '));
-      return;
-    }
-    installTo(resolveUserDir(info.dirs[0]));
-    console.log('完成。');
-    return;
-  }
-
-  if (isGlobal) {
-    const seen = new Set();
-    for (const v of Object.values(AGENT_DIRS)) {
-      for (const d of v.dirs) {
-        if (seen.has(d)) continue;
-        seen.add(d);
-        installTo(resolveUserDir(d));
-      }
-    }
-    console.log('完成。');
-    return;
-  }
-
-  const PROJECT_DIRS = [
-    '.claude/skills',
-    '.cursor/skills',
-    '.codex/skills',
-    '.config/goose/skills',
-    '.config/agents/skills',
-    '.opencode/skills',
-    '.codeium/windsurf/skills',
-    '.workbuddy/skills',
-    '.kiro/skills',
-    '.traecli/skills',
-    '.gemini/skills',
-    '.trae-cn/skills',
-    '.qwen/skills',
-    '.comate/skills',
-    '.codebuddy/skills',
-    '.kimi/skills',
-    '.agents/skills',
-  ];
-  let installedAny = false;
-  for (const d of PROJECT_DIRS) {
-    if (fs.existsSync(d)) { installTo(d); installedAny = true; }
-  }
-  if (!installedAny) {
-    console.log('未检测到项目级智能体目录。可手动复制，或用 --agent <name> / -g 装到用户级。');
-  }
-}
-
-main();
+#!/usr/bin/env node
+/**
+ * @yottameta/yotta-humanize cross-platform installer.
+ *
+ * Usage:
+ *   npx -y @yottameta/yotta-humanize --agent <name>
+ *   npx -y @yottameta/yotta-humanize --dir <path>
+ *   npx -y @yottameta/yotta-humanize -g
+ *   npx -y @yottameta/yotta-humanize
+ *   npx -y @yottameta/yotta-humanize --list
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SKILL_NAME = 'yotta-humanize';
+const PKG_ROOT = path.join(__dirname, '..');
+const COPY_SKIP = new Set(['package.json', 'bin', 'node_modules', '.git', '.github', 'test']);
+
+const AGENT_DIRS = {
+  claude:    { label: 'Claude Code',      dirs: ['.claude/skills'] },
+  cursor:    { label: 'Cursor',           dirs: ['.cursor/skills', '.agents/skills'] },
+  codex:     { label: 'Codex',            dirs: ['.codex/skills'] },
+  gemini:    { label: 'Gemini CLI',       dirs: ['.gemini/skills', '.agents/skills'] },
+  goose:     { label: 'Goose',            dirs: ['.config/goose/skills', '.agents/skills'] },
+  amp:       { label: 'Amp',              dirs: ['.config/agents/skills', '.agents/skills'] },
+  opencode:  { label: 'OpenCode',         dirs: ['.config/opencode/skills'] },
+  windsurf:  { label: 'Windsurf',         dirs: ['.codeium/windsurf/skills'] },
+  workbuddy: { label: 'WorkBuddy',        dirs: ['.workbuddy/skills'] },
+  kiro:      { label: 'Kiro',             dirs: ['.kiro/skills'] },
+  trae:      { label: 'Trae Code CLI',    dirs: ['.traecli/skills'] },
+  'trae-cn': { label: 'Trae IDE',         dirs: ['.trae-cn/skills'] },
+  qwen:      { label: 'Qwen Code',        dirs: ['.qwen/skills'] },
+  comate:    { label: 'Comate',           dirs: ['.comate/skills'] },
+  codebuddy: { label: 'CodeBuddy Code',   dirs: ['.codebuddy/skills'] },
+  kimi:      { label: 'Kimi Code CLI',    dirs: ['.kimi/skills'] },
+  agents:    { label: 'Generic AGENTS.md', dirs: ['.agents/skills'] },
+};
+
+class UsageError extends Error {}
+class TargetError extends Error {}
+class InstallError extends Error {}
+
+function usage() {
+  console.log('yotta-humanize installer');
+  console.log('');
+  console.log('Usage:');
+  console.log('  npx -y @yottameta/yotta-humanize --agent <name>  Install to an agent default directory');
+  console.log('  npx -y @yottameta/yotta-humanize --dir <path>     Install to a custom directory');
+  console.log('  npx -y @yottameta/yotta-humanize -g               Install to all known agent directories');
+  console.log('  npx -y @yottameta/yotta-humanize                  Auto-detect project-level directories');
+  console.log('  npx -y @yottameta/yotta-humanize --list           List supported agent directories');
+  console.log('');
+  console.log('Options:');
+  console.log('  --agent <name>  Agent key, see --list');
+  console.log('  --dir <path>    Custom skills directory');
+  console.log('  -g, --global    Install to all known user-level directories');
+  console.log('  --list, -l      List supported agents');
+  console.log('  -h, --help      Show this help');
+}
+
+function parseArgs(argv) {
+  const opts = { help: false, list: false, global: false, dir: null, agent: null };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') opts.help = true;
+    else if (arg === '--list' || arg === '-l') opts.list = true;
+    else if (arg === '--global' || arg === '-g') opts.global = true;
+    else if (arg === '--dir') {
+      const value = argv[++i];
+      if (!value) throw new UsageError('--dir requires a non-empty path');
+      opts.dir = value;
+    } else if (arg === '--agent') {
+      const value = argv[++i];
+      if (!value) throw new UsageError('--agent requires a non-empty name');
+      opts.agent = value.toLowerCase();
+    } else {
+      throw new UsageError('Unknown argument: ' + arg);
+    }
+  }
+  if (!opts.help) {
+    const selected = [opts.dir, opts.agent, opts.global].filter(Boolean).length;
+    if (selected > 1) throw new UsageError('Use only one of --dir, --agent, or -g');
+  }
+  return opts;
+}
+
+function codexUserDir() {
+  const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+  return path.join(base, 'skills');
+}
+
+function opencodeUserDir() {
+  const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  return path.join(base, 'opencode', 'skills');
+}
+
+function resolveUserDir(rel) {
+  if (rel === '.codex/skills') return codexUserDir();
+  if (rel === '.config/opencode/skills') return opencodeUserDir();
+  return path.join(os.homedir(), rel);
+}
+
+function displayDir(rel) {
+  if (process.platform === 'win32') return '%USERPROFILE%\\' + rel.replace(/\//g, '\\');
+  return '~/' + rel;
+}
+
+function printList() {
+  console.log('Agent -> default skill directory:');
+  for (const [key, value] of Object.entries(AGENT_DIRS)) {
+    console.log('  ' + key.padEnd(12) + value.label.padEnd(20) + value.dirs.map(displayDir).join(', '));
+  }
+  console.log('');
+  console.log('Use --dir <path> for agents not listed. CODEX_HOME and XDG_CONFIG_HOME are respected.');
+}
+
+function assertSafeTarget(target) {
+  const rel = path.relative(PKG_ROOT, target);
+  if (rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))) {
+    throw new UsageError('Target directory must be outside the skill source directory');
+  }
+}
+
+function copyDir(src, dst, skip) {
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (skip.has(entry.name)) continue;
+    const from = path.join(src, entry.name);
+    const to = path.join(dst, entry.name);
+    try {
+      if (entry.isDirectory()) {
+        fs.mkdirSync(to, { recursive: true });
+        copyDir(from, to, skip);
+      } else if (entry.isFile()) {
+        fs.copyFileSync(from, to);
+      }
+    } catch (err) {
+      throw new InstallError('Failed to copy ' + from + ' -> ' + to + ': ' + err.message);
+    }
+  }
+}
+
+function installTo(dest) {
+  if (!dest || typeof dest !== 'string') throw new UsageError('Destination directory is required');
+  const target = path.resolve(dest, SKILL_NAME);
+  assertSafeTarget(target);
+  try {
+    fs.mkdirSync(target, { recursive: true });
+    copyDir(PKG_ROOT, target, COPY_SKIP);
+    if (!fs.existsSync(path.join(target, 'SKILL.md'))) {
+      throw new InstallError('Installed directory is missing SKILL.md');
+    }
+  } catch (err) {
+    if (err instanceof UsageError || err instanceof InstallError) throw err;
+    throw new InstallError('Cannot install to ' + target + ': ' + err.message);
+  }
+  console.log('installed -> ' + target);
+  return target;
+}
+
+function projectDirs() {
+  return [
+    '.claude/skills',
+    '.cursor/skills',
+    '.codex/skills',
+    '.config/goose/skills',
+    '.config/agents/skills',
+    '.opencode/skills',
+    '.codeium/windsurf/skills',
+    '.workbuddy/skills',
+    '.kiro/skills',
+    '.traecli/skills',
+    '.gemini/skills',
+    '.trae-cn/skills',
+    '.qwen/skills',
+    '.comate/skills',
+    '.codebuddy/skills',
+    '.kimi/skills',
+    '.agents/skills',
+  ].filter((dir) => fs.existsSync(dir));
+}
+
+function run() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) { usage(); return; }
+  if (opts.list) { printList(); return; }
+
+  if (opts.dir) { installTo(opts.dir); return; }
+
+  if (opts.agent) {
+    const info = AGENT_DIRS[opts.agent];
+    if (!info) {
+      throw new UsageError('Unknown agent: ' + opts.agent + '. Available: ' + Object.keys(AGENT_DIRS).join(', ') + '. Use --dir for a custom directory.');
+    }
+    installTo(resolveUserDir(info.dirs[0]));
+    return;
+  }
+
+  if (opts.global) {
+    const seen = new Set();
+    let count = 0;
+    for (const value of Object.values(AGENT_DIRS)) {
+      for (const dir of value.dirs) {
+        if (seen.has(dir)) continue;
+        seen.add(dir);
+        installTo(resolveUserDir(dir));
+        count++;
+      }
+    }
+    console.log('Installed to ' + count + ' directories.');
+    return;
+  }
+
+  const dirs = projectDirs();
+  if (!dirs.length) {
+    throw new TargetError('No project-level agent directory detected. Use --agent <name> or --dir <path>.');
+  }
+  for (const dir of dirs) installTo(dir);
+}
+
+function main() {
+  try {
+    run();
+  } catch (err) {
+    if (err instanceof UsageError) {
+      console.error('Usage error: ' + err.message);
+      usage();
+      process.exitCode = 2;
+    } else if (err instanceof TargetError) {
+      console.error('Target error: ' + err.message);
+      process.exitCode = 4;
+    } else if (err instanceof InstallError) {
+      console.error('Install failed: ' + err.message);
+      console.error('Fix: check directory permissions and free space, then retry. Use --dir to choose another directory.');
+      process.exitCode = 1;
+    } else {
+      console.error('Unexpected error: ' + (err && err.message ? err.message : String(err)));
+      process.exitCode = 1;
+    }
+  }
+}
+
+main();

package/install.sh

@@ -1,132 +1,132 @@
-#!/usr/bin/env bash
-# yotta-humanize 多智能体安装脚本（YottaSkills 模板）
-# 用法:
-#   bash install.sh --agent <name>  # 按智能体默认用户级目录安装
-#   bash install.sh --dir <path>    # 装到指定目录（用户改过目录的智能体）
-#   bash install.sh -g              # 装到全部已知智能体用户级目录
-#   bash install.sh                  # 检测并安装到已存在的项目级目录
-#   bash install.sh --list          # 列出智能体 -> 默认目录
-set -euo pipefail
-
-SKILL_NAME="yotta-humanize"
-SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-case "$(uname -s)" in
-  MINGW*|MSYS*)
-    SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -W)"
-    ;;
-esac
-
-# 智能体 -> 用户级默认目录（--agent 装到第一个）
-# .agents/skills 并非通用目录：OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot 读取。
-# 判断当前环境：Windows Git Bash 用 %USERPROFILE%，Unix 用 ~
-_IS_WINDOWS=0
-case "$(uname -s)" in
-  MINGW*|MSYS*|CYGWIN*) _IS_WINDOWS=1 ;;
-esac
-dirs_for() {
-  case "$1" in
-    claude)     echo ".claude/skills" ;;
-    cursor)     echo ".cursor/skills .agents/skills" ;;
-    codex)      echo "__CODEX__" ;;
-    gemini)     echo ".gemini/skills .agents/skills" ;;
-    goose)      echo ".config/goose/skills .agents/skills" ;;
-    amp)        echo ".config/agents/skills .agents/skills" ;;
-    opencode)   echo "__OPENCODE__" ;;
-    windsurf)   echo ".codeium/windsurf/skills" ;;
-    workbuddy)  echo ".workbuddy/skills" ;;
-    kiro)       echo ".kiro/skills" ;;
-    trae)       echo ".traecli/skills" ;;
-    trae-cn)    echo ".trae-cn/skills" ;;
-    qwen)       echo ".qwen/skills" ;;
-    comate)     echo ".comate/skills" ;;
-    codebuddy)  echo ".codebuddy/skills" ;;
-    kimi)       echo ".kimi/skills" ;;
-    agents)     echo ".agents/skills" ;;
-    *)          return 1 ;;
-  esac
-}
-
-codex_dir() {
-  if [ -n "${CODEX_HOME:-}" ]; then printf '%s' "$CODEX_HOME/skills"; else printf '%s' "$HOME/.codex/skills"; fi
-}
-opencode_dir() {
-  if [ -n "${XDG_CONFIG_HOME:-}" ]; then printf '%s' "$XDG_CONFIG_HOME/opencode/skills"; else printf '%s' "$HOME/.config/opencode/skills"; fi
-}
-resolve_user() {
-  case "$1" in
-    __CODEX__)    codex_dir ;;
-    __OPENCODE__) opencode_dir ;;
-    *)            printf '%s' "$HOME/$1" ;;
-  esac
-}
-
-install_to() {
-  mkdir -p "$1/$SKILL_NAME"
-  cp -r "$SOURCE_DIR/." "$1/$SKILL_NAME/"
-  rm -rf "$1/$SKILL_NAME/.git"
-  echo "installed -> $1/$SKILL_NAME"
-}
-
-list() {
-  echo "智能体 -> 默认技能目录（--agent <name> 装到第一个，用户级）:"
-  for a in claude cursor codex gemini goose amp opencode windsurf workbuddy kiro trae trae-cn qwen comate codebuddy kimi agents; do
-    local dirs first
-    dirs="$(dirs_for "$a")"
-    first="${dirs%% *}"
-    case "$first" in
-      __CODEX__)    first=".codex/skills" ;;
-      __OPENCODE__) first=".config/opencode/skills" ;;
-    esac
-    if [ "$_IS_WINDOWS" = "1" ]; then
-      first="%USERPROFILE%\\${first//\//\\}"
-    else
-      first="~/$first"
-    fi
-    printf '  %-10s %s\n' "$a" "$first"
-  done
-  echo '说明：Windows 用 %USERPROFILE%，Linux/macOS 用 ~；仅收录有官方默认目录的智能体。'
-  echo '改了目录的请用 --dir <路径>，不要依赖默认位置；若设置了 CODEX_HOME / XDG_CONFIG_HOME，安装自动以该变量为准。'
-}
-
-main() {
-  local agent="" dir="" global=0 show_list=0
-  while [ $# -gt 0 ]; do
-    case "$1" in
-      --agent) shift; agent="${1:-}" ;;
-      --dir)   shift; dir="${1:-}" ;;
-      -g|--global) global=1 ;;
-      --list|-l) show_list=1 ;;
-      *) echo "未知参数: $1" >&2; exit 2 ;;
-    esac
-    shift
-  done
-
-  if [ "$show_list" = "1" ]; then list; return; fi
-  if [ -n "$dir" ]; then install_to "$dir"; echo "完成。"; return; fi
-  if [ -n "$agent" ]; then
-    local dirs first
-    if ! dirs="$(dirs_for "$agent")"; then
-      echo "未收录智能体: $agent。请用 --dir <路径> 指定技能目录。" >&2; exit 2
-    fi
-    first="${dirs%% *}"
-    install_to "$(resolve_user "$first")"; echo "完成。"; return
-  fi
-  if [ "$global" = "1" ]; then
-    echo "安装到全部已知智能体用户级目录..."
-    local dirs rel
-    for a in claude cursor codex gemini goose amp opencode windsurf workbuddy kiro trae trae-cn qwen comate codebuddy kimi agents; do
-      dirs="$(dirs_for "$a")"
-      for rel in $dirs; do install_to "$(resolve_user "$rel")"; done
-    done
-    echo "完成。"; return
-  fi
-  local installed=0 d
-  for d in .claude/skills .cursor/skills .codex/skills .config/goose/skills .config/agents/skills .opencode/skills .codeium/windsurf/skills .workbuddy/skills .kiro/skills .traecli/skills .gemini/skills .trae-cn/skills .qwen/skills .comate/skills .codebuddy/skills .kimi/skills .agents/skills; do
-    if [ -d "$d" ]; then install_to "$d"; installed=1; fi
-  done
-  if [ "$installed" = "0" ]; then
-    echo "未检测到项目级智能体目录。可用 --agent <name> / -g 装到用户级，或 --dir 指定。"
-  fi
-}
-
+#!/usr/bin/env bash
+# yotta-humanize 多智能体安装脚本（YottaSkills 模板）
+# 用法:
+#   bash install.sh --agent <name>  # 按智能体默认用户级目录安装
+#   bash install.sh --dir <path>    # 装到指定目录（用户改过目录的智能体）
+#   bash install.sh -g              # 装到全部已知智能体用户级目录
+#   bash install.sh                  # 检测并安装到已存在的项目级目录
+#   bash install.sh --list          # 列出智能体 -> 默认目录
+set -euo pipefail
+
+SKILL_NAME="yotta-humanize"
+SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+case "$(uname -s)" in
+  MINGW*|MSYS*)
+    SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -W)"
+    ;;
+esac
+
+# 智能体 -> 用户级默认目录（--agent 装到第一个）
+# .agents/skills 并非通用目录：OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot 读取。
+# 判断当前环境：Windows Git Bash 用 %USERPROFILE%，Unix 用 ~
+_IS_WINDOWS=0
+case "$(uname -s)" in
+  MINGW*|MSYS*|CYGWIN*) _IS_WINDOWS=1 ;;
+esac
+dirs_for() {
+  case "$1" in
+    claude)     echo ".claude/skills" ;;
+    cursor)     echo ".cursor/skills .agents/skills" ;;
+    codex)      echo "__CODEX__" ;;
+    gemini)     echo ".gemini/skills .agents/skills" ;;
+    goose)      echo ".config/goose/skills .agents/skills" ;;
+    amp)        echo ".config/agents/skills .agents/skills" ;;
+    opencode)   echo "__OPENCODE__" ;;
+    windsurf)   echo ".codeium/windsurf/skills" ;;
+    workbuddy)  echo ".workbuddy/skills" ;;
+    kiro)       echo ".kiro/skills" ;;
+    trae)       echo ".traecli/skills" ;;
+    trae-cn)    echo ".trae-cn/skills" ;;
+    qwen)       echo ".qwen/skills" ;;
+    comate)     echo ".comate/skills" ;;
+    codebuddy)  echo ".codebuddy/skills" ;;
+    kimi)       echo ".kimi/skills" ;;
+    agents)     echo ".agents/skills" ;;
+    *)          return 1 ;;
+  esac
+}
+
+codex_dir() {
+  if [ -n "${CODEX_HOME:-}" ]; then printf '%s' "$CODEX_HOME/skills"; else printf '%s' "$HOME/.codex/skills"; fi
+}
+opencode_dir() {
+  if [ -n "${XDG_CONFIG_HOME:-}" ]; then printf '%s' "$XDG_CONFIG_HOME/opencode/skills"; else printf '%s' "$HOME/.config/opencode/skills"; fi
+}
+resolve_user() {
+  case "$1" in
+    __CODEX__)    codex_dir ;;
+    __OPENCODE__) opencode_dir ;;
+    *)            printf '%s' "$HOME/$1" ;;
+  esac
+}
+
+install_to() {
+  mkdir -p "$1/$SKILL_NAME"
+  cp -r "$SOURCE_DIR/." "$1/$SKILL_NAME/"
+  rm -rf "$1/$SKILL_NAME/.git"
+  echo "installed -> $1/$SKILL_NAME"
+}
+
+list() {
+  echo "智能体 -> 默认技能目录（--agent <name> 装到第一个，用户级）:"
+  for a in claude cursor codex gemini goose amp opencode windsurf workbuddy kiro trae trae-cn qwen comate codebuddy kimi agents; do
+    local dirs first
+    dirs="$(dirs_for "$a")"
+    first="${dirs%% *}"
+    case "$first" in
+      __CODEX__)    first=".codex/skills" ;;
+      __OPENCODE__) first=".config/opencode/skills" ;;
+    esac
+    if [ "$_IS_WINDOWS" = "1" ]; then
+      first="%USERPROFILE%\\${first//\//\\}"
+    else
+      first="~/$first"
+    fi
+    printf '  %-10s %s\n' "$a" "$first"
+  done
+  echo '说明：Windows 用 %USERPROFILE%，Linux/macOS 用 ~；仅收录有官方默认目录的智能体。'
+  echo '改了目录的请用 --dir <路径>，不要依赖默认位置；若设置了 CODEX_HOME / XDG_CONFIG_HOME，安装自动以该变量为准。'
+}
+
+main() {
+  local agent="" dir="" global=0 show_list=0
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --agent) shift; agent="${1:-}" ;;
+      --dir)   shift; dir="${1:-}" ;;
+      -g|--global) global=1 ;;
+      --list|-l) show_list=1 ;;
+      *) echo "未知参数: $1" >&2; exit 2 ;;
+    esac
+    shift
+  done
+
+  if [ "$show_list" = "1" ]; then list; return; fi
+  if [ -n "$dir" ]; then install_to "$dir"; echo "完成。"; return; fi
+  if [ -n "$agent" ]; then
+    local dirs first
+    if ! dirs="$(dirs_for "$agent")"; then
+      echo "未收录智能体: $agent。请用 --dir <路径> 指定技能目录。" >&2; exit 2
+    fi
+    first="${dirs%% *}"
+    install_to "$(resolve_user "$first")"; echo "完成。"; return
+  fi
+  if [ "$global" = "1" ]; then
+    echo "安装到全部已知智能体用户级目录..."
+    local dirs rel
+    for a in claude cursor codex gemini goose amp opencode windsurf workbuddy kiro trae trae-cn qwen comate codebuddy kimi agents; do
+      dirs="$(dirs_for "$a")"
+      for rel in $dirs; do install_to "$(resolve_user "$rel")"; done
+    done
+    echo "完成。"; return
+  fi
+  local installed=0 d
+  for d in .claude/skills .cursor/skills .codex/skills .config/goose/skills .config/agents/skills .opencode/skills .codeium/windsurf/skills .workbuddy/skills .kiro/skills .traecli/skills .gemini/skills .trae-cn/skills .qwen/skills .comate/skills .codebuddy/skills .kimi/skills .agents/skills; do
+    if [ -d "$d" ]; then install_to "$d"; installed=1; fi
+  done
+  if [ "$installed" = "0" ]; then
+    echo "未检测到项目级智能体目录。可用 --agent <name> / -g 装到用户级，或 --dir 指定。"
+  fi
+}
+
 main "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-humanize",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "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.",
   "license": "MIT",
   "keywords": [
@@ -18,7 +18,10 @@
     "bin",
     "NOTICE",
     "CHANGELOG.md",
-    "README.zh-CN.md"
+    "README.zh-CN.md",
+    "!scripts/__pycache__",
+    "!**/__pycache__",
+    "!**/*.pyc"
   ],
   "repository": {
     "type": "git",
@@ -29,5 +32,8 @@
   },
   "bin": {
     "yotta-humanize": "bin/install.js"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.js\" && python scripts/test_yotta_humanize.py"
   }
 }

package/references/faq.md

@@ -0,0 +1,51 @@
+# 元真 FAQ / 避坑指南
+
+> 常见问题速查：文本传不进去、结果不像预期、文件报错时先看这里。
+
+## 速查索引
+
+- **输入**：怎么传文本 · UTF-8 报错 · 长文怎么处理
+- **结果**：改写变化不大 · rewrite/suggest 区别 · 会不会改坏
+- **规则**：检测原理 · CI 拦截 · 退出码
+- **使用**：什么时候自动触发 · 安装/智能体目录
+
+## 1. 怎么把文本传进去？
+
+## 1. 怎么把文本传进去？
+三种方式任选：`-f 文件.txt`（读 UTF-8 文件）、`--stdin`（管道输入）、直接传文本参数（`yotta-humanize score "这段文字"`）。注意顺序：`score / analyze / report / suggest / rewrite` 子命令 + 输入方式。
+
+## 2. 报「不是 UTF-8 编码」？
+把文件另存为 UTF-8 编码再试（记事本 → 另存为 → 编码选 UTF-8）。Windows 的 GBK/ANSI 文件需先转码。
+
+## 3. 文件太大 / 长文处理？
+建议分段处理：每段单独 `rewrite` 或 `suggest`，再拼接。复杂长文中的嵌套问题可能需要人工复核，元真只做确定性规则改写，不保证处理所有嵌套句式。
+
+## 4. 改写后变化不大？
+说明原文 AI 味本身不高（`score` 低）。先跑 `score` 看评分，再 `analyze` 看命中的规则；确需润色时用 `suggest` 获取人工润色建议，或 `rewrite` 做机械改写。
+
+## 5. rewrite 和 suggest 有什么区别？
+`rewrite`：确定性机械改写（命中规则就替换/删除），输出改写后全文 + 修复清单 + 前后评分。
+`suggest`：按优先级给改写建议（不直接改原文），适合人工精修。
+
+## 6. CI 拦截怎么用？
+`yotta-humanize rewrite --gate --threshold 40`：改写后评分仍 >= 阈值时退出码 1，可在 CI 里拦截 AI 腔内容。`--gate` 需搭配 `score` 或 `rewrite`。
+
+## 7. 退出码 0 / 1 / 4 什么意思？
+0 = 成功；1 = `--gate` 命中（评分 >= 阈值，用于 CI 拦截）；4 = 输入错误（文件不存在、无输入等）。
+
+## 8. 会不会改坏原文？
+`rewrite` 只做确定性替换/删除（规则命中才动），输出带修复清单（改了什么、改了几处）和 before/after 评分，可逐条核对。不改写事实、数据、专有名词。
+
+## 9. 检测原理是什么？
+24 类规则 + 词表（赋能、闭环、值得注意的是、综上所述、希望对你有所帮助 等 AI 常用词与句式）+ 统计突发性，全部确定性规则，不依赖任何模型，结果可复现。
+
+## 10. 边界
+只处理文本，不生成新内容；不改写事实 / 数据 / 专有名词；不破坏作者原意。AI 腔极重或嵌套复杂的文本，建议配合人工润色。
+
+## 11. 什么时候会触发？
+
+当你编辑/润色文本、给 AI 生成内容做检测、或发现文本里满是“赋能 / 闭环 / 综上所述 / 希望对你有所帮助”这类 AI 常用词时触发；用户也可以直接说“元真 / 去 AI 味 / 帮我改得像人写的”。
+
+## 12. 安装不上 / 智能体没识别怎么办？
+
+用 `npx -y @yottameta/yotta-humanize --agent <名称>` 装到已知智能体，或 `--dir <技能目录>` 装到自定义路径；未收录智能体用 `--dir`。走国内 npm 镜像遇到传播延迟时临时加 `--registry=https://registry.npmjs.org/`。装完后新会话自动加载才会生效。

package/references/walkthroughs.md

@@ -0,0 +1,28 @@
+# 元真复杂场景走查
+
+## 走查 1：公众号推文去 AI 味
+
+输入：一篇约 2000 字的“行业观察”，开头“在当今数字化浪潮的背景下……赋能……闭环……总而言之”，结尾“希望对你有所帮助”。
+
+1. 先 `score -f article.md` 拿基线分；预期偏高。
+2. `analyze` 看命中规则，优先处理套话开头/结尾、赋能/闭环等词表替换。
+3. `rewrite` 做机械改写，核对修复清单；保留事实数据与专有名词。
+4. 对判断性改写（排比拆句、模糊归因）用 `suggest` 输出人工建议，不在 rewrite 里强改。
+5. 二次 `score` 对比，确认评分下降且原意未变。
+
+## 走查 2：会议纪要不破坏正式语气
+
+输入：一段会议纪要，AI 痕迹主要是“值得注意的是”“综上所述”“我们”滥用，但语气偏正式。
+
+1. 先跑 `analyze` 分五组看命中，避免只按词表删。
+2. 正式文档优先 `suggest` 而不是 `rewrite`，让作者选择保留正式语气的改写。
+3. 检查“我们”是否真的冗余；数据、结论、待办一字不改。
+4. 输出改写建议清单供人工确认，而不是直接交付改写稿。
+
+## 走查 3：CSV/接口文案批量门禁
+
+输入：一批由 AI 生成的中文短文案，要统一过 CI 防 AI 味。
+
+1. 用 `score --stdin --gate --threshold 45` 接入发布前检查。
+2. 超阈值的条目单独 `suggest`/`rewrite`，保留作者原意。
+3. 门禁只看确定性评分，不替代人工编辑；评分低于阈值只代表未命中规则，不代表“一定不像 AI 写的”。

package/scripts/yotta_humanize.py

@@ -47,7 +47,7 @@ _HERE = Path(__file__).resolve().parent
 sys.path.insert(0, str(_HERE))
 import humanize_rules as HR  # noqa: E402
 
-VERSION = "0.1.2"
+VERSION = "0.2.0"
 TOOL_NAME = "yotta-humanize"
 TOOL_CN = "元真"
 DEFAULT_THRESHOLD = 45
@@ -515,8 +515,13 @@ def _read_text(args):
     if getattr(args, "file", None):
         p = Path(args.file)
         if not p.exists():
-            raise SystemExit("文件不存在：%s" % p)
-        return p.read_text(encoding="utf-8")
+            raise SystemExit("文件不存在：%s\n修复建议：请检查文件路径是否正确、文件名是否拼错。" % p)
+        try:
+            return p.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            raise SystemExit("无法读取文件：%s 不是 UTF-8 编码\n修复建议：请把文件另存为 UTF-8 编码后重试（记事本 → 另存为 → 编码选 UTF-8）。" % p)
+        except OSError as e:
+            raise SystemExit("无法读取文件：%s（%s）\n修复建议：请检查文件是否存在、是否有读取权限。" % (p, e))
     if getattr(args, "stdin", False):
         return _read_stdin()
     if getattr(args, "text", None):
@@ -621,7 +626,7 @@ def main(argv=None):
                 print(res["text"])
             return 0
     except Exception as e:  # noqa: BLE001
-        print("错误：%s" % e, file=sys.stderr)
+        print("错误：%s\n修复建议：请检查输入是否为 UTF-8 编码、文件是否存在；若仍报错，请把上面的错误信息反馈给开发者。" % e, file=sys.stderr)
         return 4
     return 4