npm - @yottameta/yotta-humanize - Versions diffs - 0.1.1 → 0.1.3 - Mend

@yottameta/yotta-humanize 0.1.1 → 0.1.3

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 (10) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -1,8 +1,24 @@
+## 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)
+- 安装方式统一为四方式（对齐发布规范 §3.3.1）：方式一 `npx -y @yottameta/yotta-humanize --agent <name>` / `--dir <dir>`（推荐，走 npm 源）；方式二 `git clone https://github.com/YottaMeta/yotta-humanize.git`；方式三 GitHub Download ZIP；方式四 `bash install.sh --agent/--dir/--list`。移除 `npx skills` 与 `-g` 推荐；中英双 README 安装节同步。
+- 版本对齐：package.json / SKILL.md / CHANGELOG / 引擎 VERSION / 测试断言 / README 锚点 = 0.1.2。
+- 无功能变更（仅文档与版本同步）。
 ## v0.1.1 (2026-08-28)
-中英双语 README 对齐（老张拍板「英文门面 + 中文全档」）：
+中英双语 README 对齐（确定「英文门面 + 中文全档」）：
 - **README.md 改为英文**：作为 GitHub / npm / ClawHub 首页的英文门面（翻译 + 精简，覆盖定位 / 核心价值 / 命令 / 快速使用 / 安装 / 使用示例 / 边界 / 开发校验全流程）。
 - **新增 README.zh-CN.md**：原中文完整主文档整体平移，顶部加语言切换链接。
@@ -12,7 +28,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 / 逗号密度）。
 - **确定性改写**：词表替换（赋能→支持、抓手→切入点、闭环→流程…）、套话 / 聊天残渣 / 奉承 / 免责删除、破折号 / 感叹号限流；输出修复清单与前后评分。
@@ -20,4 +36,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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -42,7 +42,7 @@ It is not tied to any single platform: an agent-agnostic toolkit that works in a
 | **Chinese-first** | Wordlists and patterns for Chinese AI-flavor (jargon / clichés / parallelism / chat residue) curated from scratch, not translated English rules |
 | **Detect + rewrite in one** | score / analyze / report / suggest / rewrite — one command from detection to rewriting |
 | **Reviewable** | Rewrites output a fix list and before/after scores so humans can verify item by item |
-| **Ecosystem distribution** | GitHub + npm + ClawHub synced; install via npx / install.sh / manual copy |
+| **Ecosystem distribution** | GitHub + npm + ClawHub synced; four install methods (npx / git clone / Download ZIP / install.sh) |
 ## Commands
@@ -86,51 +86,39 @@ Exit codes (same semantics as the YuanAn / YuanShen / Yuandun family): **0** = s
 ## Install
-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).
+Pick any of the four methods below; the order is the recommended priority. Skill files always come from **npm** (GitHub can be slow without a proxy; npm supports mirrors).
-### Method 1: npm (recommended, one-liner)
-```bash
-# domestic mirror (optional): npm config set registry https://registry.npmmirror.com
-npx -y @yottameta/yotta-humanize -g
-npx -y @yottameta/yotta-humanize --dir <your-skills-dir>   # any agent: install to a specific directory
+### Method 1: npm one-liner (recommended)
+```text
+# Optional China mirror: npm config set registry https://registry.npmmirror.com
+npx -y @yottameta/yotta-humanize --agent <agent-name>      # install to the agent's default user-level skills dir
+npx -y @yottameta/yotta-humanize --dir <your-skills-dir>   # point to the skills dir itself (e.g. ~/.codex/skills)
 ```
-> 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.
-### Method 2: install.sh one-shot
-After obtaining the skill folder (npm pack unpack or git clone), enter the folder:
-```bash
-bash install.sh -g    # user level; bash install.sh --list shows all directories
-bash install.sh --agent codex   # specific agent (--list shows available ones)
-bash install.sh       # project level: auto-detect existing .claude/.cursor/.codex skills dirs
-bash install.sh --dir /path/to/skills
+- `--agent <name>` installs to that agent's default user-level directory; `--list` shows each agent's default directory.
+- `--dir <path>` installs to the given directory; for agents not in the preset list, point `--dir` at their skills directory.
+- If the mirror has not synced the new package (404): add `--registry=https://registry.npmjs.org/` (a proxy may be needed in China), or wait for the mirror cache.
+### Method 2: git clone (developers / git available)
+```text
+git clone https://github.com/YottaMeta/yotta-humanize.git <your-skills-dir>/yotta-humanize
+```
+### Method 3: GitHub Download ZIP (manual / no git)
+On the GitHub repository `YottaMeta/yotta-humanize`, click **Code → Download ZIP**, unzip it and put the `yotta-humanize` folder into the agent's skills directory.
+### Method 4: install.sh (multi-agent one-liner script)
+```text
+bash install.sh --agent <name>   # install to the agent's default user-level directory
+bash install.sh --dir <path>     # install to the given directory
+bash install.sh --list           # list agents -> default directories
 ```
-> Covers 17 agent families including Trae / Qwen / Comate / CodeBuddy / Kimi. Windows users: works with Git Bash; otherwise use method 3.
-### Method 3: manual copy
-Copy the whole yotta-humanize folder into the target agent's skills directory. Common locations (user level; Windows uses %USERPROFILE%, Linux/macOS uses ~):
-| Agent | User-level directory | Project-level directory |
-|---|---|---|
-| Codex | %USERPROFILE%\.codex\skills\yotta-humanize\ | .codex\skills\ |
-| Claude Code | %USERPROFILE%\.claude\skills\yotta-humanize\ | .claude\skills\ |
-| Cursor | %USERPROFILE%\.cursor\skills\yotta-humanize\ | .cursor\skills\ |
-| Windsurf | %USERPROFILE%\.codeium\windsurf\skills\yotta-humanize\ | .windsurf\skills\ |
-| opencode | %USERPROFILE%\.config\opencode\skills\yotta-humanize\ | .opencode\skills\ |
-| Gemini | %USERPROFILE%\.gemini\skills\yotta-humanize\ | .gemini\skills\ |
-| Goose | %USERPROFILE%\.config\goose\skills\yotta-humanize\ | .goose\skills\ |
-| Amp | %USERPROFILE%\.config\agents\skills\yotta-humanize\ | .agents\skills\ |
-| Kiro | %USERPROFILE%\.kiro\skills\yotta-humanize\ | .kiro\skills\ |
-| WorkBuddy | %USERPROFILE%\.workbuddy\skills\yotta-humanize\ | .workbuddy\skills\ |
-| Trae Code CLI | %USERPROFILE%\.traecli\skills\yotta-humanize\ | .traecli\skills\ |
-| Trae IDE (CN) | %USERPROFILE%\.trae-cn\skills\yotta-humanize\ | .trae\skills\ |
-| Qwen Code | %USERPROFILE%\.qwen\skills\yotta-humanize\ | .qwen\skills\ |
-| Comate | %USERPROFILE%\.comate\skills\yotta-humanize\ | .comate\skills\ |
-| CodeBuddy | %USERPROFILE%\.codebuddy\skills\yotta-humanize\ | .codebuddy\skills\ |
-| Kimi | %USERPROFILE%\.kimi\skills\yotta-humanize\ | .kimi\skills\ |
-| Generic AGENTS.md | %USERPROFILE%\.agents\skills\yotta-humanize\ | .agents\skills\ |
-> 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.
+> Method 1 uses the npm registry (npmmirror / npmjs) and does not depend on GitHub; Methods 2/3 use GitHub and may fail without a proxy in China.
 ## Usage examples (AI agent)
 1. Hook this repo's SKILL.md into any AI agent's skill/rule system (see install above).
@@ -153,6 +141,40 @@ Copy the whole yotta-humanize folder into the target agent's skills directory. C
 - **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 CHANGED Viewed

@@ -43,7 +43,7 @@ AI 生成的中文文本有一眼可辨的「AI 腔」：空泛升华（标志
 | **中文优先** | 针对中文 AI 腔（黑话 / 套话 / 排比 / 聊天残渣）自研词表与句式，非英文规则直译 |
 | **检测 + 改写一体** | score / analyze / report / suggest / rewrite 全流程，一条命令从检测到改写 |
 | **可复核** | 改写输出修复清单与前后评分，人工可逐条核对 |
-| **生态分发** | GitHub + npm + ClawHub 三源同步发布；npx / install.sh / 手动复制三种安装方式 |
+| **生态分发** | GitHub + npm + ClawHub 三源同步发布；npx / git clone / Download ZIP / install.sh 四种安装方式 |
 ## 功能体系
@@ -87,51 +87,39 @@ python3 scripts/yotta_humanize.py score -f article.md --gate --threshold 45
 ## 安装
-三种方式任选其一，技能文件统一从 **npm** 获取（GitHub 无代理时较慢，npm 可配国内镜像加速）。
+以下四种方式任选，顺序即推荐优先级；技能文件一律从 **npm** 获取（GitHub 无代理较慢，npm 支持镜像）。
-### 方式一：npm（推荐，一行安装）
-```bash
-# 国内加速（可选）：npm config set registry https://registry.npmmirror.com
-npx -y @yottameta/yotta-humanize -g
-npx -y @yottameta/yotta-humanize --dir <你的技能目录>   # 任意智能体：指定目录安装
+### 方式一：npm 一行装（推荐）
+```text
+# 可选国内加速：npm config set registry https://registry.npmmirror.com
+npx -y @yottameta/yotta-humanize --agent <智能体名称>      # 装到指定智能体默认用户级技能目录
+npx -y @yottameta/yotta-humanize --dir <智能体的技能目录>  # 指到技能目录本身（如 ~/.codex/skills）
 ```
-> 智能体不在预置列表里？用 --dir 指定它的 skills 目录，或手动复制（方式三）。--list 可查看各智能体对应的默认目录。想手动拿文件也可 npm pack @yottameta/yotta-humanize 解包后按方式二/三安装。
-### 方式二：install.sh 一键安装
-获取技能文件夹后（npm pack 解包或 git clone），进入技能文件夹：
-```bash
-bash install.sh -g    # 用户级；bash install.sh --list 查看全部目录
-bash install.sh --agent codex   # 指定智能体（--list 可查看可用项）
-bash install.sh       # 项目级：自动检测已存在的 .claude/.cursor/.codex 等 skills 目录
-bash install.sh --dir /path/to/skills
+- `--agent <name>` 自动装到该智能体默认用户级目录；`--list` 可查看各智能体默认目录。
+- `--dir <路径>` 装到指定的技能目录；未收录的智能体用 `--dir` 指到它的技能目录。
+- npmmirror 未同步新包（404）：加 `--registry=https://registry.npmjs.org/`（国内需代理），或稍等镜像缓存。
+### 方式二：git clone（开发者 / 有 git 环境）
+```text
+git clone https://github.com/YottaMeta/yotta-humanize.git <智能体的技能目录>/yotta-humanize
+```
+### 方式三：GitHub 下载压缩包（手动 / 无 git 环境）
+在 GitHub 仓库 `YottaMeta/yotta-humanize` 点 **Code → Download ZIP**，解压后把 `yotta-humanize` 文件夹放进智能体技能目录。
+### 方式四：install.sh（多智能体一键脚本）
+```text
+bash install.sh --agent <name>   # 装到指定智能体默认用户级目录
+bash install.sh --dir <path>     # 装到指定目录
+bash install.sh --list           # 列出智能体 -> 默认目录
 ```
-> 覆盖 17 类智能体，含国内 Trae / Qwen / Comate / CodeBuddy / Kimi。Windows 用户：装有 Git Bash 即可用；否则用方式三手动复制。
-### 方式三：手动复制
-把整个 yotta-humanize 文件夹复制到目标智能体的 skills 目录。常见位置（用户级；Windows 用 %USERPROFILE%，Linux/macOS 用 ~）：
-| 智能体 | 用户级目录 | 项目级目录 |
-|---|---|---|
-| Codex | %USERPROFILE%\.codex\skills\yotta-humanize\ | .codex\skills\ |
-| Claude Code | %USERPROFILE%\.claude\skills\yotta-humanize\ | .claude\skills\ |
-| Cursor | %USERPROFILE%\.cursor\skills\yotta-humanize\ | .cursor\skills\ |
-| Windsurf | %USERPROFILE%\.codeium\windsurf\skills\yotta-humanize\ | .windsurf\skills\ |
-| opencode | %USERPROFILE%\.config\opencode\skills\yotta-humanize\ | .opencode\skills\ |
-| Gemini | %USERPROFILE%\.gemini\skills\yotta-humanize\ | .gemini\skills\ |
-| Goose | %USERPROFILE%\.config\goose\skills\yotta-humanize\ | .goose\skills\ |
-| Amp | %USERPROFILE%\.config\agents\skills\yotta-humanize\ | .agents\skills\ |
-| Kiro | %USERPROFILE%\.kiro\skills\yotta-humanize\ | .kiro\skills\ |
-| WorkBuddy | %USERPROFILE%\.workbuddy\skills\yotta-humanize\ | .workbuddy\skills\ |
-| Trae Code CLI | %USERPROFILE%\.traecli\skills\yotta-humanize\ | .traecli\skills\ |
-| Trae IDE（国内） | %USERPROFILE%\.trae-cn\skills\yotta-humanize\ | .trae\skills\ |
-| Qwen Code | %USERPROFILE%\.qwen\skills\yotta-humanize\ | .qwen\skills\ |
-| Comate | %USERPROFILE%\.comate\skills\yotta-humanize\ | .comate\skills\ |
-| CodeBuddy | %USERPROFILE%\.codebuddy\skills\yotta-humanize\ | .codebuddy\skills\ |
-| Kimi | %USERPROFILE%\.kimi\skills\yotta-humanize\ | .kimi\skills\ |
-| 通用 AGENTS.md | %USERPROFILE%\.agents\skills\yotta-humanize\ | .agents\skills\ |
-> Codex 默认目录若设置了环境变量 CODEX_HOME，以该变量为准；opencode 若设置 XDG_CONFIG_HOME 同理。.agents\skills 并非通用目录，仅 OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot 等会读取，Claude Code 与 Codex 默认不读。不确定时用 --dir 指定，或让该智能体自行安装。
+> 方式一走 npm 源（npmmirror / npmjs），不依赖 GitHub；方式二 / 三走 GitHub，国内无代理可能失败。
 ## 使用示例（AI 智能体）
 1. 将本仓库的 SKILL.md 接入任意 AI 智能体的技能/规则系统（见上方安装）。
@@ -148,6 +136,40 @@ bash install.sh --dir /path/to/skills
 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 CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 name: yotta-humanize
-version: 0.1.1
+version: 0.1.3
 description: 元真 —— 去 AI 味的中文写作编辑技能：检测器引擎（24 类规则 + 词表 + 统计突发性）识别并改写 AI 腔文本，让中文写作更自然、更像人写的。触发：编辑 / 润色文本、去 AI 味、让文章 / 文案 / 回复更像人写、发现文本充斥着 AI 常用词与句式（赋能 / 闭环 / 值得注意的是 / 综上所述 / 希望对你有所帮助 等）、给 AI 生成的中文稿件做检测与改写。边界：只处理文本，不生成新内容；不改写事实 / 数据 / 专有名词；不破坏作者原意；改写为确定性规则，不依赖模型。
 license: MIT
 ---

package/bin/install.js CHANGED Viewed

@@ -1,163 +1,163 @@
-#!/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 装到用户级。');
-  }
-}
+#!/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();

package/install.sh CHANGED Viewed

@@ -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 CHANGED Viewed

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

package/references/faq.md ADDED Viewed

@@ -0,0 +1,34 @@
+# 元真 FAQ / 避坑指南
+> 常见问题速查：文本传不进去、结果不像预期、文件报错时先看这里。
+## 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 腔极重或嵌套复杂的文本，建议配合人工润色。

package/scripts/yotta_humanize.py CHANGED Viewed

@@ -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.1"
+VERSION = "0.1.3"
 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