@yottameta/yotta-humanize 0.1.3 → 0.2.1

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+## v0.2.1 (2026-09-19)
+
+- 修复：`score` / `analyze` / `report` / `suggest` / `rewrite` 以位置参数直接传文本时报 `expected string or bytes-like object, got 'list'`（`_read_text` 把文本列表原样返回，未拼接）；`-f` / `--stdin` 路径不受影响。
+- 补回归测试：位置参数单文本 / 多词拼接共 3 项（修复前复现红，修复后全量 158/158 通过）。
+
+## 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)
 
 评测反馈优化（文档 + 错误提示，功能不变）。

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yotta-humanize
-version: 0.1.3
+version: 0.2.1
 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,51 +1,97 @@
 #!/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          # 列出智能体 -> 默认目录
+ * @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']);
 
-// 智能体 -> 用户级默认技能目录（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
+  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'] }, // 特判：$XDG_CONFIG_HOME
+  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'] },
+  'trae-cn': { label: 'Trae IDE',         dirs: ['.trae-cn/skills'] },
   qwen:      { label: 'Qwen Code',        dirs: ['.qwen/skills'] },
-  comate:    { label: 'Comate 文心快码',   dirs: ['.comate/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'] },
+  agents:    { label: 'Generic AGENTS.md', dirs: ['.agents/skills'] },
 };
 
-// Codex 用户级目录特判：优先 $CODEX_HOME/skills，否则 ~/.codex/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');
 }
 
-// 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');
@@ -57,82 +103,65 @@ function resolveUserDir(rel) {
   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;
+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.');
+}
 
-  if (explicitDir) { installTo(explicitDir); return; }
+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');
+  }
+}
 
-  if (agent) {
-    const info = AGENT_DIRS[agent];
-    if (!info) {
-      console.log('未收录智能体: ' + agent + '。请用 --dir <路径> 指定技能目录。');
-      console.log('可用: ' + Object.keys(AGENT_DIRS).join(', '));
-      return;
+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);
     }
-    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));
-      }
+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');
     }
-    console.log('完成。');
-    return;
+  } 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;
+}
 
-  const PROJECT_DIRS = [
+function projectDirs() {
+  return [
     '.claude/skills',
     '.cursor/skills',
     '.codex/skills',
@@ -150,14 +179,67 @@ function main() {
     '.codebuddy/skills',
     '.kimi/skills',
     '.agents/skills',
-  ];
-  let installedAny = false;
-  for (const d of PROJECT_DIRS) {
-    if (fs.existsSync(d)) { installTo(d); installedAny = true; }
+  ].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 (!installedAny) {
-    console.log('未检测到项目级智能体目录。可手动复制，或用 --agent <name> / -g 装到用户级。');
+
+  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();
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-humanize",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "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

@@ -2,6 +2,15 @@
 
 > 常见问题速查：文本传不进去、结果不像预期、文件报错时先看这里。
 
+## 速查索引
+
+- **输入**：怎么传文本 · UTF-8 报错 · 长文怎么处理
+- **结果**：改写变化不大 · rewrite/suggest 区别 · 会不会改坏
+- **规则**：检测原理 · CI 拦截 · 退出码
+- **使用**：什么时候自动触发 · 安装/智能体目录
+
+## 1. 怎么把文本传进去？
+
 ## 1. 怎么把文本传进去？
 三种方式任选：`-f 文件.txt`（读 UTF-8 文件）、`--stdin`（管道输入）、直接传文本参数（`yotta-humanize score "这段文字"`）。注意顺序：`score / analyze / report / suggest / rewrite` 子命令 + 输入方式。
 
@@ -32,3 +41,11 @@
 
 ## 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/test_yotta_humanize.py

@@ -178,6 +178,22 @@ def test_cli():
     check("score 文本输出为数字", r.returncode == 0 and r.stdout.strip().isdigit(),
           "rc=%d out=%r" % (r.returncode, r.stdout))
 
+    # 位置参数直接传文本（v0.2.1 回归：_read_text 曾把 args.text 列表原样返回）
+    r = _run(["score", ai])
+    check("score 位置参数直接传文本",
+          r.returncode == 0 and r.stdout.strip().isdigit(),
+          "rc=%d out=%r err=%r" % (r.returncode, r.stdout[:60], r.stderr[:80]))
+
+    r = _run(["rewrite", ai])
+    check("rewrite 位置参数直接传文本",
+          r.returncode == 0 and "改写后评分" in r.stdout,
+          "rc=%d err=%r" % (r.returncode, r.stderr[:80]))
+
+    r = _run(["score", "众所周知，", "未来可期。"])
+    check("score 多词位置参数按空格拼接",
+          r.returncode == 0 and r.stdout.strip().isdigit(),
+          "rc=%d out=%r err=%r" % (r.returncode, r.stdout[:60], r.stderr[:80]))
+
     r = _run(["score", "--gate", "--threshold", "1"], inp=ai)
     check("score --gate 高分退出码 1", r.returncode == 1, "rc=%d" % r.returncode)
 

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.3"
+VERSION = "0.2.1"
 TOOL_NAME = "yotta-humanize"
 TOOL_CN = "元真"
 DEFAULT_THRESHOLD = 45
@@ -525,7 +525,7 @@ def _read_text(args):
     if getattr(args, "stdin", False):
         return _read_stdin()
     if getattr(args, "text", None):
-        return args.text
+        return " ".join(args.text)
     if not sys.stdin.isatty():
         return _read_stdin()
     raise SystemExit("缺少输入：用 -f 指定文件、--stdin 读管道，或直接传文本参数。")