@yottameta/yotta-code-quality 0.3.3 → 0.4.0

package/CHANGELOG.md

@@ -1,8 +1,22 @@
+## v0.4.0 (2026-09-08)
+
+**评测驱动完善**：新增 FAQ 与复杂场景走查，安装器错误处理与测试补齐。
+
+- 新增 references/faq.md 与 references/walkthroughs.md。
+- 安装器支持 --help、参数校验、统一退出码与人话错误提示。
+- 新增安装器测试，覆盖未知智能体、缺参、成功安装与产物形态。
+
 # 更新日志
 
+## v0.3.4 (2026-08-29)
+
+- 安装方式统一为四方式（对齐发布规范 §3.3.1）：方式一 `npx -y @yottameta/yotta-code-quality --agent <name>` / `--dir <dir>`（推荐，走 npm 源）；方式二 `git clone https://github.com/YottaMeta/yotta-code-quality.git`；方式三 GitHub Download ZIP；方式四 `bash install.sh --agent/--dir/--list`。移除 `npx skills` 与 `-g` 推荐；中英双 README 安装节同步。
+- 版本对齐：package.json / SKILL.md / CHANGELOG / 引擎 VERSION / 测试断言 / README 锚点 = 0.3.4。
+- 无功能变更（仅文档与版本同步）。
+
 ## v0.3.3 (2026-08-28)
 
-中英双语 README 对齐（老张拍板「英文门面 + 中文全档」）：
+中英双语 README 对齐：
 
 - **README.md 改为英文**：作为 GitHub / npm / ClawHub 首页的英文门面（翻译 + 精简，覆盖定位 / 核心价值 / 工作流程 / 风险矩阵 / 目录结构 / 安装 / 使用 / 升级卸载 / FAQ / 来源与许可全流程）。
 - **新增 README.zh-CN.md**：原中文完整主文档整体平移，顶部加语言切换链接。

package/README.md

@@ -144,50 +144,39 @@ yotta-code-quality/
 
 ## 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-code-quality -g
-npx -y @yottameta/yotta-code-quality --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-code-quality --agent <agent-name>      # install to the agent's default user-level skills dir
+npx -y @yottameta/yotta-code-quality --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-code-quality and unpack it to install via method 2 / 3.
 
-### Method 2: install.sh one-shot
-```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-code-quality.git <your-skills-dir>/yotta-code-quality
 ```
-> 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-code-quality` folder into the target agent's skills directory. Common locations (user level; Windows uses %USERPROFILE%, Linux/macOS uses ~):
+### Method 3: GitHub Download ZIP (manual / no git)
 
-| Agent | User-level directory | Project-level directory |
-|---|---|---|
-| Codex | %USERPROFILE%\.codex\skills\yotta-code-quality\ | .codex\skills\ |
-| Claude Code | %USERPROFILE%\.claude\skills\yotta-code-quality\ | .claude\skills\ |
-| Cursor | %USERPROFILE%\.cursor\skills\yotta-code-quality\ | .cursor\skills\ |
-| Windsurf | %USERPROFILE%\.codeium\windsurf\skills\yotta-code-quality\ | .windsurf\skills\ |
-| opencode | %USERPROFILE%\.config\opencode\skills\yotta-code-quality\ | .opencode\skills\ |
-| Gemini | %USERPROFILE%\.gemini\skills\yotta-code-quality\ | .gemini\skills\ |
-| Goose | %USERPROFILE%\.config\goose\skills\yotta-code-quality\ | .goose\skills\ |
-| Amp | %USERPROFILE%\.config\agents\skills\yotta-code-quality\ | .agents\skills\ |
-| Kiro | %USERPROFILE%\.kiro\skills\yotta-code-quality\ | .kiro\skills\ |
-| WorkBuddy | %USERPROFILE%\.workbuddy\skills\yotta-code-quality\ | .workbuddy\skills\ |
-| Trae Code CLI | %USERPROFILE%\.traecli\skills\yotta-code-quality\ | .traecli\skills\ |
-| Trae IDE (CN) | %USERPROFILE%\.trae-cn\skills\yotta-code-quality\ | .trae\skills\ |
-| Qwen Code | %USERPROFILE%\.qwen\skills\yotta-code-quality\ | .qwen\skills\ |
-| Comate | %USERPROFILE%\.comate\skills\yotta-code-quality\ | .comate\skills\ |
-| CodeBuddy | %USERPROFILE%\.codebuddy\skills\yotta-code-quality\ | .codebuddy\skills\ |
-| Kimi | %USERPROFILE%\.kimi\skills\yotta-code-quality\ | .kimi\skills\ |
-| Generic AGENTS.md | %USERPROFILE%\.agents\skills\yotta-code-quality\ | .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.
+On the GitHub repository `YottaMeta/yotta-code-quality`, click **Code → Download ZIP**, unzip it and put the `yotta-code-quality` 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
+```
+
+> 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
 
 Say "review this PR", "结对评审" or "发版前扫一眼" in conversation, or call `/yotta-code-quality` directly. Optional flags are listed above.
@@ -216,7 +205,7 @@ Agent: PR mode → .code-quality.yaml config → auto scope → 7 steps in pr-re
 
 ## Upgrade / uninstall
 
-- **Upgrade**: rerun the install command to overwrite with the latest (npm: `npx -y @yottameta/yotta-code-quality -g`; install.sh: rerun inside the skill folder). Version is on npm.
+- **Upgrade**: reinstall the latest version to overwrite — rerun the install command you used (e.g. `npx -y @yottameta/yotta-code-quality --agent <name>` or `bash install.sh --agent <name>`). Old files in the skill directory are replaced; other project files are untouched.
 - **Uninstall**: delete the `yotta-code-quality/` folder under the target agent's skills directory.
 - **No side effects**: the skill writes nothing outside the project; the optional trend file (`.code-quality-history.json`) is only generated when you enable `history: true`, at the repo root.
 
@@ -238,6 +227,11 @@ Agent: PR mode → .code-quality.yaml config → auto scope → 7 steps in pr-re
 
 See [CHANGELOG.md](./CHANGELOG.md).
 
+## 参考文档
+
+- 常见问题：`references/faq.md`
+- 复杂场景走查：`references/walkthroughs.md`
+
 ## License
 
 [MIT](./LICENSE) © hyhmrright (original methodology) + YottaMeta (this packaging). "Yuanzhi" / "yotta-code-quality" and the YottaMeta family names (yotta-* prefix) are YottaMeta brand identifiers; derived works must not reuse them, see [NOTICE](./NOTICE).

package/README.zh-CN.md

@@ -157,51 +157,39 @@ yotta-code-quality/
 
 ## 安装
 
-三种方式任选其一，技能文件统一从 **npm** 获取（GitHub 无代理时较慢，npm 可配国内镜像加速）。
+以下四种方式任选，顺序即推荐优先级；技能文件一律从 **npm** 获取（GitHub 无代理较慢，npm 支持镜像）。
 
-### 方式一：npm（推荐，一行安装）
-```bash
-# 国内加速（可选）：npm config set registry https://registry.npmmirror.com
-npx -y @yottameta/yotta-code-quality -g
-npx -y @yottameta/yotta-code-quality --dir <你的技能目录>   # 任意智能体：指定目录安装
+### 方式一：npm 一行装（推荐）
+
+```text
+# 可选国内加速：npm config set registry https://registry.npmmirror.com
+npx -y @yottameta/yotta-code-quality --agent <智能体名称>      # 装到指定智能体默认用户级技能目录
+npx -y @yottameta/yotta-code-quality --dir <智能体的技能目录>  # 指到技能目录本身（如 ~/.codex/skills）
 ```
-> 智能体不在预置列表？用 `--dir` 指定它的 skills 目录，或手动复制（方式三）。`--list` 可查看各智能体对应的默认目录。想手动拿文件也可 `npm pack @yottameta/yotta-code-quality` 解包后按方式二/三安装。
 
-### 方式二：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-code-quality.git <智能体的技能目录>/yotta-code-quality
+```
+
+### 方式三：GitHub 下载压缩包（手动 / 无 git 环境）
+
+在 GitHub 仓库 `YottaMeta/yotta-code-quality` 点 **Code → Download ZIP**，解压后把 `yotta-code-quality` 文件夹放进智能体技能目录。
+
+### 方式四：install.sh（多智能体一键脚本）
+
+```text
+bash install.sh --agent <name>   # 装到指定智能体默认用户级目录
+bash install.sh --dir <path>     # 装到指定目录
+bash install.sh --list           # 列出智能体 -> 默认目录
 ```
-> Windows 用户：装有 Git Bash 即可用；否则用方式三手动复制。
-
-### 方式三：手动复制
-把整个 `yotta-code-quality` 文件夹复制到目标智能体的 skills 目录。常见位置（用户级；Windows 用 `%USERPROFILE%`，Linux/macOS 用 `~`）：
-
-| 智能体 | 用户级目录 | 项目级目录 |
-|---|---|---|
-| Codex | `%USERPROFILE%\.codex\skills\yotta-code-quality\` | `.codex\skills\` |
-| Claude Code | `%USERPROFILE%\.claude\skills\yotta-code-quality\` | `.claude\skills\` |
-| Cursor | `%USERPROFILE%\.cursor\skills\yotta-code-quality\` | `.cursor\skills\` |
-| Windsurf | `%USERPROFILE%\.codeium\windsurf\skills\yotta-code-quality\` | `.windsurf\skills\` |
-| opencode | `%USERPROFILE%\.config\opencode\skills\yotta-code-quality\` | `.opencode\skills\` |
-| Gemini | `%USERPROFILE%\.gemini\skills\yotta-code-quality\` | `.gemini\skills\` |
-| Goose | `%USERPROFILE%\.config\goose\skills\yotta-code-quality\` | `.goose\skills\` |
-| Amp | `%USERPROFILE%\.config\agents\skills\yotta-code-quality\` | `.agents\skills\` |
-| Kiro | `%USERPROFILE%\.kiro\skills\yotta-code-quality\` | `.kiro\skills\` |
-| WorkBuddy | `%USERPROFILE%\.workbuddy\skills\yotta-code-quality\` | `.workbuddy\skills\` |
-| Trae Code CLI | `%USERPROFILE%\.traecli\skills\yotta-code-quality\` | `.traecli\skills\` |
-| Trae IDE（国内） | `%USERPROFILE%\.trae-cn\skills\yotta-code-quality\` | `.trae\skills\` |
-| Qwen Code | `%USERPROFILE%\.qwen\skills\yotta-code-quality\` | `.qwen\skills\` |
-| Comate | `%USERPROFILE%\.comate\skills\yotta-code-quality\` | `.comate\skills\` |
-| CodeBuddy | `%USERPROFILE%\.codebuddy\skills\yotta-code-quality\` | `.codebuddy\skills\` |
-| Kimi | `%USERPROFILE%\.kimi\skills\yotta-code-quality\` | `.kimi\skills\` |
-| 通用 AGENTS.md | `%USERPROFILE%\.agents\skills\yotta-code-quality\` | `.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，国内无代理可能失败。
 ## 使用
 
 对话中说「review this PR」「结对评审」「发版前扫一眼」，或直接调用 `/yotta-code-quality`。可选参数见上文「可选参数」。
@@ -230,7 +218,7 @@ bash install.sh --dir /path/to/skills
 
 ## 升级与卸载
 
-- **升级**：重新执行一次安装命令即可覆盖为最新版（npm 方式：`npx -y @yottameta/yotta-code-quality -g`；install.sh 方式：重新在技能文件夹运行）。版本号见 npm。
+- **升级**：重新安装最新版覆盖即可——重跑你用的安装命令（如 `npx -y @yottameta/yotta-code-quality --agent <name>` 或 `bash install.sh --agent <name>`）。技能目录内旧文件会被替换；不影响项目中其他文件。
 - **卸载**：删除目标智能体 skills 目录下的 `yotta-code-quality/` 文件夹即可。
 - **无副作用**：技能不写项目外文件；可选的历史/趋势文件（`.code-quality-history.json`）只在你开启 `history: true` 时生成，位于仓库根。
 
@@ -246,4 +234,9 @@ bash install.sh --dir /path/to/skills
 ## 来源与许可
 
 - **方法论**蒸馏自 12 本经典软件工程著作及开源社区质量审查实践（MIT）；原始方法论版权归 hyhmrright，本技能在其基础上重写为单一自包含、跨智能体通用的版本，并增补 R7 / UX1 / 按需加载会话契约。
-- **许可：** MIT —— 详见 `LICENSE`（版权人：hyhmrright（原始方法论）+ YottaMeta（本打包））。
+- **许可：** MIT —— 详见 `LICENSE`（版权人：hyhmrright（原始方法论）+ YottaMeta（本打包））。
+
+## 参考文档
+
+- references/faq.md
+- references/walkthroughs.md

package/SKILL.md

@@ -9,7 +9,7 @@ description: >-
   「结对评审」/「发版前扫一眼」/ yotta-code-quality.
   Do NOT trigger for: greenfield "how do I write X" with no code, pure syntax questions,
   or tool/framework questions with no shared code.
-version: 0.3.3
+version: 0.4.0
 license: MIT
 ---
 
@@ -128,3 +128,5 @@ Scoring math and report template: **`references/common.md` only** (do not duplic
 | `references/examples.md` | Tone calibration |
 | `references/AGENTS-template.md` | Optional repo drop-in |
 | `references/hooks.json` | Optional dangerous-command hook |
+| `references/faq.md` | Common questions and troubleshooting |
+| `references/walkthroughs.md` | Complex review walkthroughs |

package/bin/install.js

@@ -1,51 +1,97 @@
 #!/usr/bin/env node
 /**
- * yotta-code-quality 跨平台安装器（YottaSkills）
- * 用法:
- *   npx -y @yottameta/yotta-code-quality --agent <name>  # 按智能体默认用户级目录安装（推荐）
- *   npx -y @yottameta/yotta-code-quality --dir PATH      # 装到指定目录（用户改了目录的智能体）
- *   npx -y @yottameta/yotta-code-quality -g              # 安装到全部已知智能体用户级目录
- *   npx -y @yottameta/yotta-code-quality                 # 安装到检测到的项目级目录
- *   npx -y @yottameta/yotta-code-quality --list          # 列出智能体 -> 默认目录
+ * @yottameta/yotta-code-quality cross-platform installer.
+ *
+ * Usage:
+ *   npx -y @yottameta/yotta-code-quality --agent <name>
+ *   npx -y @yottameta/yotta-code-quality --dir <path>
+ *   npx -y @yottameta/yotta-code-quality -g
+ *   npx -y @yottameta/yotta-code-quality
+ *   npx -y @yottameta/yotta-code-quality --list
  */
 'use strict';
+
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
 const SKILL_NAME = 'yotta-code-quality';
 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-code-quality installer');
+  console.log('');
+  console.log('Usage:');
+  console.log('  npx -y @yottameta/yotta-code-quality --agent <name>  Install to an agent default directory');
+  console.log('  npx -y @yottameta/yotta-code-quality --dir <path>     Install to a custom directory');
+  console.log('  npx -y @yottameta/yotta-code-quality -g               Install to all known agent directories');
+  console.log('  npx -y @yottameta/yotta-code-quality                  Auto-detect project-level directories');
+  console.log('  npx -y @yottameta/yotta-code-quality --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-code-quality",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "Pair-style code quality reviewer: twelve book-grounded decay risks (R1-R6, T1-T6) plus release-safety and first-paint UX checks; Iron Law findings (Symptom -> Source -> Consequence -> Remedy) and 0-100 Health Score.",
   "license": "MIT",
   "keywords": [
@@ -31,5 +31,8 @@
   },
   "bin": {
     "yotta-code-quality": "bin/install.js"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.js\""
   }
 }

package/references/faq.md

@@ -0,0 +1,50 @@
+# 元质常见问题
+
+## 速查索引
+
+- **触发**：什么时候用 · 每次都读全部文档吗
+- **评审**：评分怎么算 · 大 PR 怎么办 · 没有测试怎么办
+- **集成**：CI / hook 怎么接
+- **边界**：和编译器 / 测试的关系 · 输出格式
+
+---
+
+## 1. 什么时候应该触发？
+
+用户要求 review、检查代码质量、判断是否可合并、识别技术债、评估测试质量，或在发布前做质量门时触发。
+
+## 2. 每次都要读全部参考文档吗？
+
+不需要。先读 `SKILL.md`，按模式加载：日常 review 读 `pr-review-guide.md` 与 `common.md`；需要风险定义时读 `decay-risks.md` / `test-decay-risks.md`；发布或 UX 专项再读 `editorial-extensions.md`。
+
+## 3. 健康分怎么算？
+
+按发现数量与严重度加权，具体公式和报告模板在 `references/common.md`。分数用于趋势比较，不替代人工判断。
+
+## 4. 发现必须按什么格式写？
+
+使用 Iron Law 四段：Symptom → Source → Consequence → Remedy。缺少任一段应补齐后再输出。
+
+## 5. 大 PR 怎么处理？
+
+先分层：入口 / 配置 / 数据流 / 测试 / 文档。优先 R2（正确性），再看 R1 / R3 / R4；只对高风险路径展开全文，不在低风险格式化改动上消耗篇幅。
+
+## 6. 没有测试的项目怎么评审？
+
+明确标注“测试信号缺失”，并把它作为发现输出；不要假设测试通过。可建议最小回归清单。
+
+## 7. 可以接入 CI 或 hook 吗？
+
+可以。`references/hooks.json` 提供危险命令拦截示例，`references/AGENTS-template.md` 可作为仓库规则模板。接入前先在本地试运行。
+
+## 8. 发现太多时怎么排序？
+
+按 Blocker > Major > Warning > Suggestion。同级里先输出影响正确性和发布安全的发现。
+
+## 9. 它会替代编译器或测试吗？
+
+不会。元质负责评审决策与风险解释；编译、测试、运行验证仍由对应工具完成。
+
+## 10. 输出可以直接贴到 PR 吗？
+
+可以。按 `references/common.md` 的模板输出，包含健康分、发现清单与复核建议。

package/references/walkthroughs.md

@@ -0,0 +1,30 @@
+# 元质复杂场景走查
+
+## 走查 1：小改动发布评审
+
+输入：一个 40 行的服务层改动，修改错误处理并新增一个参数。
+
+1. 先读 diff 与调用点，确认入口和影响面。
+2. 按 R2 检查错误分支是否改变语义。
+3. 按 R3 检查新增参数是否有默认值与调用方兼容。
+4. 按 T1/T3 检查测试是否覆盖新错误分支。
+5. 输出 2-3 条高价值发现，附 Iron Law 四段与健康分。
+
+## 走查 2：大型 PR 分层评审
+
+输入：一个 2000 行重构 PR。
+
+1. 只看文件清单与依赖图，先分出入口、领域、基础设施、测试。
+2. 对高风险模块做全文评审，低风险机械改动只抽样。
+3. 优先检查 R4（耦合）、R5（结构）、R6（命名）。
+4. 输出分层结论和必须人工复核的路径。
+5. 标注“未全文评审”的范围，不假装全覆盖。
+
+## 走查 3：首屏 UX 专项
+
+输入：一个新页面，功能可用但首屏偏慢。
+
+1. 按 UX1 检查首屏关键路径。
+2. 识别阻塞渲染的脚本、字体和图片。
+3. 按 R7 检查是否存在不必要的复杂度。
+4. 输出可验证的优化建议，如“延迟加载非首屏模块”“压缩首屏图片”。