@yottameta/yotta-code-quality 0.3.4 → 0.4.0

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## v0.4.0 (2026-09-08)
+
+**评测驱动完善**：新增 FAQ 与复杂场景走查，安装器错误处理与测试补齐。
+
+- 新增 references/faq.md 与 references/walkthroughs.md。
+- 安装器支持 --help、参数校验、统一退出码与人话错误提示。
+- 新增安装器测试，覆盖未知智能体、缺参、成功安装与产物形态。
+
 # 更新日志
 
 ## v0.3.4 (2026-08-29)
@@ -8,7 +16,7 @@
 
 ## v0.3.3 (2026-08-28)
 
-中英双语 README 对齐（老张拍板「英文门面 + 中文全档」）：
+中英双语 README 对齐：
 
 - **README.md 改为英文**：作为 GitHub / npm / ClawHub 首页的英文门面（翻译 + 精简，覆盖定位 / 核心价值 / 工作流程 / 风险矩阵 / 目录结构 / 安装 / 使用 / 升级卸载 / FAQ / 来源与许可全流程）。
 - **新增 README.zh-CN.md**：原中文完整主文档整体平移，顶部加语言切换链接。

package/README.md

@@ -227,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

@@ -234,4 +234,9 @@ bash install.sh --list           # 列出智能体 -> 默认目录
 ## 来源与许可
 
 - **方法论**蒸馏自 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.4
+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.4",
+  "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. 输出可验证的优化建议，如“延迟加载非首屏模块”“压缩首屏图片”。