@yottameta/yotta-intel 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # 更新日志
 
+## v0.2.2 (2026-10-01)
+
+- 安装器卫生批次：`bin/install.js` / `install.sh` 统一（未知参数报错 exit 2、`--help` / `--version`、残留清理白名单、嵌套载荷保留）；由模板单一真源渲染，接入漂移门禁。
+- 自带安装器测试（`test/install.test.js`）更新为统一行为断言。
+
+## v0.2.1 (2026-09-25)
+
+维护性发布：安装器加固 + README 锁定版本。
+
+- 安装器：拒绝对符号链接目标写入、目标不是目录时拒绝、不做整目录删除。
+- README（中英）：安装命令改为锁定版本写法（去掉 `@版本` 即跟随最新）。
+- 输出示例与 references 头部版本号同步 0.2.1。
+- 修复：IPv4 前导零写法（`010.000.000.001`）归一为 `10.0.0.1` —— Python 3.9.5 起
+  `ipaddress.IPv4Address` 拒绝前导零八位组，旧引擎会静默丢掉该地址；`999.1.1.1` 仍判非法。
+
 ## v0.2.0 (2026-09-09)
 
 - 评测完善批 2：新增 references/faq.md（12 条常见问题 + 速查索引 + 安装排障）；SKILL.md 增加 FAQ 速查节。

package/README.md

@@ -91,7 +91,7 @@ python3 scripts/yotta_intel.py refang --path safe.txt
 Sample text output:
 
 ```
-元情 yotta-intel v0.2.0 —— IOC 提取结果
+元情 yotta-intel v0.2.1 —— IOC 提取结果
 共发现 2 个 IOC：
 
 ■ IPv4 地址（ipv4）
@@ -108,8 +108,8 @@ Pick any of the four methods below; the order is the recommended priority. Skill
 
 ```text
 # Optional China mirror: npm config set registry https://registry.npmmirror.com
-npx -y @yottameta/yotta-intel --agent <agent-name>      # install to the agent's default user-level skills dir
-npx -y @yottameta/yotta-intel --dir <your-skills-dir>   # point to the skills dir itself (e.g. ~/.codex/skills)
+npx -y @yottameta/yotta-intel@0.2.2 --agent <agent-name>      # install to the agent's default user-level skills dir
+npx -y @yottameta/yotta-intel@0.2.2 --dir <your-skills-dir>   # point to the skills dir itself (e.g. ~/.codex/skills)
 ```
 
 - `--agent <name>` installs to that agent's default user-level directory; `--list` shows each agent's default directory.

package/README.zh-CN.md

@@ -99,7 +99,7 @@ python3 scripts/yotta_intel.py refang --path safe.txt
 输出示例（text）：
 
 ```
-元情 yotta-intel v0.2.0 —— IOC 提取结果
+元情 yotta-intel v0.2.1 —— IOC 提取结果
 共发现 2 个 IOC：
 
 ■ IPv4 地址（ipv4）
@@ -116,8 +116,8 @@ python3 scripts/yotta_intel.py refang --path safe.txt
 
 ```text
 # 可选国内加速：npm config set registry https://registry.npmmirror.com
-npx -y @yottameta/yotta-intel --agent <智能体名称>      # 装到指定智能体默认用户级技能目录
-npx -y @yottameta/yotta-intel --dir <智能体的技能目录>  # 指到技能目录本身（如 ~/.codex/skills）
+npx -y @yottameta/yotta-intel@0.2.2 --agent <智能体名称>      # 装到指定智能体默认用户级技能目录
+npx -y @yottameta/yotta-intel@0.2.2 --dir <智能体的技能目录>  # 指到技能目录本身（如 ~/.codex/skills）
 ```
 
 - `--agent <name>` 自动装到该智能体默认用户级目录；`--list` 可查看各智能体默认目录。

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yotta-intel
-version: 0.2.0
+version: 0.2.2
 description: 元情 —— 跨智能体的威胁情报 IOC 提取与规范化技能：零依赖自研从文本 / 日志 / 报告中提取 IP（IPv4/IPv6）、域名、URL、邮箱、哈希（MD5/SHA1/SHA256/SHA512）与 CVE 编号，识别并还原 defang 写法，去重、归一化后输出 CSV / JSON / STIX-lite。触发：用户给出含可疑 IP / 域名 / URL / 哈希的威胁情报文本、恶意样本分析报告、钓鱼邮件或日志，要提取 IOC、规范化、去重、转格式、共享情报时。边界：纯本地离线提取与规范化；不联网查证、不下载样本、不主动扫描任何系统；仅用于已获授权 / 自有资产 / 教学环境的安全分析。
 license: MIT
 ---

package/bin/install.js

@@ -1,223 +1,314 @@
 #!/usr/bin/env node
 /**
- * @yottameta/yotta-intel cross-platform installer.
+ * yotta-intel 跨平台安装器（YottaSkills）
  *
- * Usage:
- *   npx -y @yottameta/yotta-intel --agent <name>
- *   npx -y @yottameta/yotta-intel --dir <path>
- *   npx -y @yottameta/yotta-intel -g
- *   npx -y @yottameta/yotta-intel
- *   npx -y @yottameta/yotta-intel --list
+ * 用法:
+ *   npx -y @yottameta/yotta-intel --agent <name>   # 按智能体默认用户级目录安装（推荐）
+ *   npx -y @yottameta/yotta-intel --dir <path>     # 装到指定目录（用户改了目录的智能体）
+ *   npx -y @yottameta/yotta-intel -g               # 安装到全部已知智能体用户级目录
+ *   npx -y @yottameta/yotta-intel                  # 安装到检测到的项目级目录
+ *   npx -y @yottameta/yotta-intel --list           # 列出智能体 -> 默认目录
+ *   npx -y @yottameta/yotta-intel --dry-run        # 只显示将写入的目标，不写文件
+ *   npx -y @yottameta/yotta-intel --version        # 显示版本
+ *   npx -y @yottameta/yotta-intel --help           # 显示帮助
+ *
+ * 退出码: 0 成功 / 1 安装失败 / 2 用法错误 / 4 目标错误
  */
 'use strict';
-
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
 const SKILL_NAME = 'yotta-intel';
 const PKG_ROOT = path.join(__dirname, '..');
-const COPY_SKIP = new Set(['package.json', 'bin', 'node_modules', '.git', '.github', 'test']);
 
+// 顶层开发文件 / 目录：只在安装包顶层跳过；技能包内嵌套同名载荷必须保留。
+// 与 install.sh 同口径：开发件与运行时不相关目录一律不落目标。
+const TOP_SKIP = [
+  'package.json', 'package-lock.json', 'bin', 'lib', 'test',
+  '.github', '.git', '.gitignore', '.npmignore', '.gitattributes',
+  '.yotta', '.tmp', 'install.sh', 'node_modules',
+];
+const TOP_SKIP_SET = new Set(TOP_SKIP);
+// 缓存 / 编译产物：任意层级跳过，安装时同样清理。
+const CACHE_DIRS = new Set(['__pycache__', '.pytest_cache', '.mypy_cache']);
+
+class UsageError extends Error {}
+class TargetError extends Error {}
+class InstallError extends Error {}
+
+// 智能体 -> 用户级默认技能目录（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:     { 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'] },
+  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'] },
+  '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: 'Generic AGENTS.md', dirs: ['.agents/skills'] },
+  agents:    { label: '通用 AGENTS.md',    dirs: ['.agents/skills'] },
 };
 
-class UsageError extends Error {}
-class TargetError extends Error {}
-class InstallError extends Error {}
+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',
+];
+
+// 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 displayDir(rel) {
+  if (process.platform === 'win32') return '%USERPROFILE%\\' + rel.replace(/\//g, '\\');
+  return '~/' + rel;
+}
+
+function skillVersion() {
+  try {
+    const data = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8'));
+    return data.version || null;
+  } catch (_) {
+    return null;
+  }
+}
 
 function usage() {
-  console.log('yotta-intel installer');
+  console.log(SKILL_NAME + ' 安装器（YottaSkills）');
   console.log('');
-  console.log('Usage:');
-  console.log('  npx -y @yottameta/yotta-intel --agent <name>  Install to an agent default directory');
-  console.log('  npx -y @yottameta/yotta-intel --dir <path>     Install to a custom directory');
-  console.log('  npx -y @yottameta/yotta-intel -g               Install to all known agent directories');
-  console.log('  npx -y @yottameta/yotta-intel                  Auto-detect project-level directories');
-  console.log('  npx -y @yottameta/yotta-intel --list           List supported agent directories');
+  console.log('用法:');
+  console.log('  node bin/install.js --agent <name>   按智能体默认用户级目录安装（推荐）');
+  console.log('  node bin/install.js --dir <path>     装到指定目录（用户改了目录的智能体）');
+  console.log('  node bin/install.js -g               安装到全部已知智能体用户级目录');
+  console.log('  node bin/install.js                  安装到检测到的项目级目录');
   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');
+  console.log('参数:');
+  console.log('  --agent <name>  智能体键名，见 --list');
+  console.log('  --dir <path>    自定义技能目录');
+  console.log('  -g, --global    安装到全部已知用户级目录');
+  console.log('  --list, -l      列出支持的智能体目录');
+  console.log('  --dry-run       只显示将写入的目标，不写文件');
+  console.log('  --version, -v   显示版本');
+  console.log('  --help, -h      显示帮助');
+  console.log('  --yes, -y       兼容参数（-g 不再强制要求）');
+  console.log('');
+  console.log('退出码: 0 成功 / 1 安装失败 / 2 用法错误 / 4 目标错误');
 }
 
 function parseArgs(argv) {
-  const opts = { help: false, list: false, global: false, dir: null, agent: null };
+  const opts = { help: false, version: false, list: false, global: false, dryRun: false, yes: 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 === '--version' || arg === '-v') opts.version = true;
     else if (arg === '--list' || arg === '-l') opts.list = true;
     else if (arg === '--global' || arg === '-g') opts.global = true;
+    else if (arg === '--dry-run') opts.dryRun = true;
+    else if (arg === '--yes' || arg === '-y') opts.yes = true;
     else if (arg === '--dir') {
       const value = argv[++i];
-      if (!value) throw new UsageError('--dir requires a non-empty path');
+      if (!value) throw new UsageError('--dir 需要一个非空路径');
       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();
+      if (!value) throw new UsageError('--agent 需要一个非空名称');
+      opts.agent = String(value).toLowerCase();
     } else {
-      throw new UsageError('Unknown argument: ' + arg);
+      throw new UsageError('未知参数: ' + arg);
     }
   }
-  if (!opts.help) {
+  if (!opts.help && !opts.version) {
     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');
+    if (selected > 1) throw new UsageError('--dir / --agent / -g 只能选一个');
   }
   return opts;
 }
 
-function codexUserDir() {
-  const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
-  return path.join(base, 'skills');
-}
-
-function opencodeUserDir() {
-  const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
-  return path.join(base, 'opencode', 'skills');
-}
-
-function resolveUserDir(rel) {
-  if (rel === '.codex/skills') return codexUserDir();
-  if (rel === '.config/opencode/skills') return opencodeUserDir();
-  return path.join(os.homedir(), rel);
-}
-
-function displayDir(rel) {
-  if (process.platform === 'win32') return '%USERPROFILE%\\' + rel.replace(/\//g, '\\');
-  return '~/' + rel;
-}
-
 function printList() {
-  console.log('Agent -> default skill directory:');
+  console.log('智能体 -> 默认技能目录（--agent <name> 装到第一个，用户级）:');
   for (const [key, value] of Object.entries(AGENT_DIRS)) {
-    console.log('  ' + key.padEnd(12) + value.label.padEnd(20) + value.dirs.map(displayDir).join(', '));
+    const resolved = value.dirs.map(displayDir);
+    console.log('  ' + key.padEnd(10) + value.label.padEnd(18) + resolved.join('、'));
   }
-  console.log('');
-  console.log('Use --dir <path> for agents not listed. CODEX_HOME and XDG_CONFIG_HOME are respected.');
+  console.log('\n说明：Windows 用 %USERPROFILE%，Linux/macOS 用 ~；仅收录有官方默认目录的智能体。');
+  console.log('改了目录的请用 --dir <路径>，不要依赖默认位置；若设置了 CODEX_HOME / XDG_CONFIG_HOME，安装自动以该变量为准。');
 }
 
 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');
+    throw new UsageError('目标目录不能在技能源目录内（防止自装自毁）');
   }
 }
 
-function copyDir(src, dst, skip) {
+function shouldSkipCache(name, isFile) {
+  if (CACHE_DIRS.has(name)) return true;
+  if (isFile && (name.endsWith('.pyc') || name.endsWith('.pyo'))) return true;
+  return false;
+}
+
+function copyDir(src, dst, topLevel) {
   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 {
+    // 只跳过安装包顶层开发文件；template/ 等嵌套同名载荷必须保留。
+    if (topLevel && TOP_SKIP_SET.has(entry.name)) continue;
+    if (shouldSkipCache(entry.name, entry.isFile())) 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, false);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(s, d);
+    }
+  }
+}
+
+// 清理旧版安装残留（fail-closed 白名单）：
+// 仅在目标目录已存在且含 SKILL.md 时触发；只删顶层开发项 + 任意层级缓存；
+// 不整目录删除、不跟随符号链接。
+function cleanResidue(target) {
+  const removed = [];
+  let stat = null;
+  try { stat = fs.statSync(target); } catch (_) { return removed; }
+  if (!stat.isDirectory()) return removed;
+  if (!fs.existsSync(path.join(target, 'SKILL.md'))) return removed;
+  for (const name of TOP_SKIP) {
+    const p = path.join(target, name);
+    let entry = null;
+    try { entry = fs.lstatSync(p); } catch (_) { continue; }
+    if (entry.isSymbolicLink()) continue;
+    fs.rmSync(p, { recursive: true, force: true });
+    removed.push(name);
+  }
+  const walk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const p = path.join(dir, entry.name);
+      if (entry.isSymbolicLink()) continue;
       if (entry.isDirectory()) {
-        fs.mkdirSync(to, { recursive: true });
-        copyDir(from, to, skip);
-      } else if (entry.isFile()) {
-        fs.copyFileSync(from, to);
+        if (CACHE_DIRS.has(entry.name)) {
+          fs.rmSync(p, { recursive: true, force: true });
+          removed.push(path.relative(target, p));
+        } else {
+          walk(p);
+        }
+      } else if (entry.isFile() && (entry.name.endsWith('.pyc') || entry.name.endsWith('.pyo'))) {
+        fs.unlinkSync(p);
+        removed.push(path.relative(target, p));
       }
-    } catch (err) {
-      throw new InstallError('Failed to copy ' + from + ' -> ' + to + ': ' + err.message);
     }
-  }
+  };
+  walk(target);
+  return removed;
 }
 
-function installTo(dest) {
-  if (!dest || typeof dest !== 'string') throw new UsageError('Destination directory is required');
+function installTo(dest, opts) {
+  if (!dest || typeof dest !== 'string') throw new UsageError('目标目录不能为空');
   const target = path.resolve(dest, SKILL_NAME);
   assertSafeTarget(target);
+  if (opts.dryRun) {
+    console.log('[dry-run] 将安装到 -> ' + target);
+    return target;
+  }
   try {
+    for (const rel of cleanResidue(target)) console.log('已清理残留: ' + rel);
     fs.mkdirSync(target, { recursive: true });
-    copyDir(PKG_ROOT, target, COPY_SKIP);
+    copyDir(PKG_ROOT, target, true);
     if (!fs.existsSync(path.join(target, 'SKILL.md'))) {
-      throw new InstallError('Installed directory is missing SKILL.md');
+      throw new InstallError('安装结果缺少 SKILL.md');
     }
   } catch (err) {
-    if (err instanceof UsageError || err instanceof InstallError) throw err;
-    throw new InstallError('Cannot install to ' + target + ': ' + err.message);
+    if (err instanceof UsageError || err instanceof TargetError || err instanceof InstallError) throw err;
+    throw new InstallError('安装到 ' + target + ' 失败: ' + err.message);
   }
   console.log('installed -> ' + target);
   return target;
 }
 
-function projectDirs() {
-  return [
-    '.claude/skills',
-    '.cursor/skills',
-    '.codex/skills',
-    '.config/goose/skills',
-    '.config/agents/skills',
-    '.opencode/skills',
-    '.codeium/windsurf/skills',
-    '.workbuddy/skills',
-    '.kiro/skills',
-    '.traecli/skills',
-    '.gemini/skills',
-    '.trae-cn/skills',
-    '.qwen/skills',
-    '.comate/skills',
-    '.codebuddy/skills',
-    '.kimi/skills',
-    '.agents/skills',
-  ].filter((dir) => fs.existsSync(dir));
-}
-
 function run() {
   const opts = parseArgs(process.argv.slice(2));
   if (opts.help) { usage(); return; }
+  if (opts.version) {
+    const version = skillVersion();
+    if (!version) {
+      console.error(SKILL_NAME + ' 版本未知（未找到 package.json）');
+      process.exitCode = 1;
+      return;
+    }
+    console.log(SKILL_NAME + ' v' + version);
+    return;
+  }
   if (opts.list) { printList(); return; }
 
-  if (opts.dir) { installTo(opts.dir); return; }
+  if (opts.dir) { installTo(opts.dir, opts); 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.');
+      throw new UsageError('未收录智能体: ' + opts.agent + '。可用: ' + Object.keys(AGENT_DIRS).join(', ') + '；自定义目录请用 --dir <路径>。');
     }
-    installTo(resolveUserDir(info.dirs[0]));
+    installTo(resolveUserDir(info.dirs[0]), opts);
+    console.log('完成。');
     return;
   }
 
   if (opts.global) {
     const seen = new Set();
-    let count = 0;
     for (const value of Object.values(AGENT_DIRS)) {
-      for (const dir of value.dirs) {
-        if (seen.has(dir)) continue;
-        seen.add(dir);
-        installTo(resolveUserDir(dir));
-        count++;
+      for (const rel of value.dirs) {
+        if (seen.has(rel)) continue;
+        seen.add(rel);
+        installTo(resolveUserDir(rel), opts);
       }
     }
-    console.log('Installed to ' + count + ' directories.');
+    if (!opts.dryRun) console.log('完成。');
     return;
   }
 
-  const dirs = projectDirs();
+  const dirs = PROJECT_DIRS.filter((d) => fs.existsSync(d));
   if (!dirs.length) {
-    throw new TargetError('No project-level agent directory detected. Use --agent <name> or --dir <path>.');
+    throw new TargetError('未检测到项目级智能体目录。可用 --agent <name> 装到用户级，或用 --dir <路径> 指定目录。');
   }
-  for (const dir of dirs) installTo(dir);
+  for (const dir of dirs) installTo(dir, opts);
+  if (!opts.dryRun) console.log('完成。');
 }
 
 function main() {
@@ -225,18 +316,18 @@ function main() {
     run();
   } catch (err) {
     if (err instanceof UsageError) {
-      console.error('Usage error: ' + err.message);
+      console.error('用法错误: ' + err.message);
       usage();
       process.exitCode = 2;
     } else if (err instanceof TargetError) {
-      console.error('Target error: ' + err.message);
+      console.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.');
+      console.error('安装失败: ' + err.message);
+      console.error('修复建议: 检查目录权限与磁盘空间后重试，或用 --dir 换一个目录。');
       process.exitCode = 1;
     } else {
-      console.error('Unexpected error: ' + (err && err.message ? err.message : String(err)));
+      console.error('未知错误: ' + (err && err.message ? err.message : String(err)));
       process.exitCode = 1;
     }
   }

package/install.sh

@@ -1,28 +1,30 @@
 #!/usr/bin/env bash
-# yotta-intel 多智能体安装脚本（YottaSkills 模板）
+# yotta-intel 多智能体安装脚本（YottaSkills）
 # 用法:
 #   bash install.sh --agent <name>  # 按智能体默认用户级目录安装
 #   bash install.sh --dir <path>    # 装到指定目录（用户改过目录的智能体）
 #   bash install.sh -g              # 装到全部已知智能体用户级目录
-#   bash install.sh                  # 检测并安装到已存在的项目级目录
+#   bash install.sh                 # 检测并安装到已存在的项目级目录
 #   bash install.sh --list          # 列出智能体 -> 默认目录
+#   bash install.sh --dry-run       # 只显示将写入的目标，不写文件
+#   bash install.sh --version       # 显示版本
+#   bash install.sh --help          # 显示帮助
+# 退出码: 0 成功 / 1 安装失败 / 2 用法错误 / 4 目标错误
 set -euo pipefail
 
 SKILL_NAME="yotta-intel"
 SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+_IS_WINDOWS=0
 case "$(uname -s)" in
   MINGW*|MSYS*)
     SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -W)"
+    _IS_WINDOWS=1
     ;;
+  CYGWIN*) _IS_WINDOWS=1 ;;
 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" ;;
@@ -60,17 +62,153 @@ resolve_user() {
   esac
 }
 
+skill_version() {
+  local pkg="$SOURCE_DIR/package.json" v=""
+  [ -f "$pkg" ] || return 0
+  if command -v awk >/dev/null 2>&1; then
+    v="$(awk -F'"' '{for (i=1;i<=NF;i++) if ($i=="version") {print $(i+2); exit}}' "$pkg" 2>/dev/null || true)"
+  fi
+  if [ -z "$v" ]; then
+    v="$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$pkg" 2>/dev/null | head -n 1 || true)"
+  fi
+  printf '%s' "$v"
+}
+
+usage() {
+  echo "$SKILL_NAME 安装脚本（YottaSkills）"
+  echo ""
+  echo "用法:"
+  echo "  bash install.sh --agent <name>   按智能体默认用户级目录安装（推荐）"
+  echo "  bash install.sh --dir <path>     装到指定目录（用户改了目录的智能体）"
+  echo "  bash install.sh -g               安装到全部已知智能体用户级目录"
+  echo "  bash install.sh                  安装到检测到的项目级目录"
+  echo ""
+  echo "参数:"
+  echo "  --agent <name>  智能体键名，见 --list"
+  echo "  --dir <path>    自定义技能目录"
+  echo "  -g, --global    安装到全部已知用户级目录"
+  echo "  --list, -l      列出支持的智能体目录"
+  echo "  --dry-run       只显示将写入的目标，不写文件"
+  echo "  --version, -v   显示版本"
+  echo "  --help, -h      显示帮助"
+  echo "  --yes, -y       兼容参数（-g 不再强制要求）"
+  echo ""
+  echo "退出码: 0 成功 / 1 安装失败 / 2 用法错误 / 4 目标错误"
+}
+
+resolve_path() {
+  # 与 SOURCE_DIR 同一风格（Windows Git Bash 用 pwd -W），供路径包含判断使用
+  local p="$1"
+  if [ "$_IS_WINDOWS" = "1" ]; then
+    (cd "$p" 2>/dev/null && pwd -W)
+  else
+    (cd "$p" 2>/dev/null && pwd -P)
+  fi
+}
+
+assert_safe_target() {
+  local dest="$1" src_real dest_real parent
+  src_real="$(resolve_path "$SOURCE_DIR")" || return 0
+  if [ -d "$dest" ]; then
+    dest_real="$(resolve_path "$dest")" || return 0
+  else
+    parent="$(dirname "$dest")"
+    dest_real="$(resolve_path "$parent")" || return 0
+    dest_real="$dest_real/$(basename "$dest")"
+  fi
+  case "$dest_real" in
+    "$src_real"|"$src_real"/*)
+      echo "安装失败：目标目录不能在技能源目录内（防止自装自毁）" >&2
+      return 1
+      ;;
+  esac
+  return 0
+}
+
+# 清理旧版安装残留（fail-closed 白名单）：仅在目标目录已存在且含 SKILL.md 时触发；
+# 只删顶层开发项 + 任意层级缓存；不整目录删除、不跟随符号链接。
+DEV_SKIP="package.json package-lock.json bin lib test .github .git .gitignore .npmignore .gitattributes .yotta .tmp install.sh node_modules"
+clean_residue() {
+  local dest="$1" name p
+  [ -d "$dest" ] || return 0
+  [ -f "$dest/SKILL.md" ] || return 0
+  for name in $DEV_SKIP; do
+    p="$dest/$name"
+    [ -L "$p" ] && continue
+    if [ -e "$p" ]; then
+      rm -rf -- "$p"
+      echo "已清理残留: $name"
+    fi
+  done
+  find "$dest" -type d \( -name '__pycache__' -o -name '.pytest_cache' -o -name '.mypy_cache' \) -prune -exec rm -rf -- {} + 2>/dev/null || true
+  find "$dest" -type f \( -name '*.pyc' -o -name '*.pyo' \) -delete 2>/dev/null || true
+}
+
+# 复制技能本体：顶层跳过开发件与运行时不相关目录（嵌套同名保留）；
+# 任意层级跳过缓存（__pycache__ / .pytest_cache / .mypy_cache / *.pyc / *.pyo）。
+copy_tree() {
+  local src="$1" dst="$2" top="$3" entry base
+  mkdir -p "$dst"
+  for entry in "$src"/* "$src"/.[!.]* "$src"/..?*; do
+    [ -e "$entry" ] || [ -L "$entry" ] || continue
+    base="$(basename "$entry")"
+    case "$base" in
+      __pycache__|.pytest_cache|.mypy_cache) continue ;;
+    esac
+    if [ "$top" = "1" ]; then
+      case " $DEV_SKIP " in
+        *" $base "*) continue ;;
+      esac
+    fi
+    if [ -d "$entry" ] && [ ! -L "$entry" ]; then
+      copy_tree "$entry" "$dst/$base" 0 || return 1
+    else
+      case "$base" in
+        *.pyc|*.pyo) continue ;;
+      esac
+      cp -RP "$entry" "$dst/$base" || return 1
+    fi
+  done
+}
+
 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"
+  local base="$1" dry="$2" dest
+  dest="$base/$SKILL_NAME"
+  if [ -L "$base" ]; then
+    echo "安装失败：目标目录是符号链接，拒绝跟随：$base" >&2
+    return 1
+  fi
+  if [ -e "$base" ] && [ ! -d "$base" ]; then
+    echo "安装失败：目标路径已存在且不是目录：$base" >&2
+    return 1
+  fi
+  if [ -L "$dest" ]; then
+    echo "安装失败：技能目录是符号链接，拒绝跟随：$dest" >&2
+    return 1
+  fi
+  if [ -e "$dest" ] && [ ! -d "$dest" ]; then
+    echo "安装失败：技能路径已存在且不是目录：$dest" >&2
+    return 1
+  fi
+  assert_safe_target "$dest" || return 1
+  if [ "$dry" = "1" ]; then
+    echo "[dry-run] 将安装到 -> $dest"
+    return 0
+  fi
+  clean_residue "$dest"
+  mkdir -p "$dest" || return 1
+  copy_tree "$SOURCE_DIR" "$dest" 1 || return 1
+  if [ ! -f "$dest/SKILL.md" ]; then
+    echo "安装失败：结果缺少 SKILL.md" >&2
+    return 1
+  fi
+  echo "installed -> $dest"
 }
 
 list() {
   echo "智能体 -> 默认技能目录（--agent <name> 装到第一个，用户级）:"
+  local a dirs first
   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
@@ -89,44 +227,101 @@ list() {
 }
 
 main() {
-  local agent="" dir="" global=0 show_list=0
+  local agent="" dir="" global=0 show_list=0 show_help=0 show_version=0 dry=0
   while [ $# -gt 0 ]; do
     case "$1" in
-      --agent) shift; agent="${1:-}" ;;
-      --dir)   shift; dir="${1:-}" ;;
-      -g|--global) global=1 ;;
+      --help|-h) show_help=1 ;;
+      --version|-v) show_version=1 ;;
       --list|-l) show_list=1 ;;
+      -g|--global) global=1 ;;
+      --dry-run) dry=1 ;;
+      --yes|-y) : ;;
+      --agent)
+        shift
+        if [ $# -eq 0 ] || [ -z "${1:-}" ]; then
+          echo "用法错误: --agent 需要一个非空名称" >&2
+          exit 2
+        fi
+        agent="$1"
+        ;;
+      --dir)
+        shift
+        if [ $# -eq 0 ] || [ -z "${1:-}" ]; then
+          echo "用法错误: --dir 需要一个非空路径" >&2
+          exit 2
+        fi
+        dir="$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 [ "$show_help" = "1" ]; then usage; return 0; fi
+  if [ "$show_version" = "1" ]; then
+    local v
+    v="$(skill_version)"
+    if [ -z "$v" ]; then
+      echo "$SKILL_NAME 版本未知（未找到 package.json）" >&2
+      exit 1
+    fi
+    echo "$SKILL_NAME v$v"
+    return 0
+  fi
+  if [ "$show_list" = "1" ]; then list; return 0; fi
+
+  local selected=0
+  [ -n "$dir" ] && selected=$((selected + 1))
+  [ -n "$agent" ] && selected=$((selected + 1))
+  [ "$global" = "1" ] && selected=$((selected + 1))
+  if [ "$selected" -gt 1 ]; then
+    echo "用法错误: --dir / --agent / -g 只能选一个" >&2
+    exit 2
+  fi
+
+  if [ -n "$dir" ]; then
+    install_to "$dir" "$dry" || exit 1
+    [ "$dry" = "1" ] || echo "完成。"
+    return 0
+  fi
   if [ -n "$agent" ]; then
     local dirs first
     if ! dirs="$(dirs_for "$agent")"; then
-      echo "未收录智能体: $agent。请用 --dir <路径> 指定技能目录。" >&2; exit 2
+      echo "未收录智能体: $agent。可用 --list 查看，或 --dir <路径> 指定。" >&2
+      exit 2
     fi
     first="${dirs%% *}"
-    install_to "$(resolve_user "$first")"; echo "完成。"; return
+    install_to "$(resolve_user "$first")" "$dry" || exit 1
+    [ "$dry" = "1" ] || echo "完成。"
+    return 0
   fi
   if [ "$global" = "1" ]; then
-    echo "安装到全部已知智能体用户级目录..."
-    local dirs rel
+    local a dirs rel seen=" "
     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
+      dirs="$(dirs_for "$a")" || continue
+      for rel in $dirs; do
+        case "$seen" in
+          *" $rel "*) continue ;;
+        esac
+        seen="$seen$rel "
+        install_to "$(resolve_user "$rel")" "$dry" || exit 1
+      done
     done
-    echo "完成。"; return
+    [ "$dry" = "1" ] || echo "完成。"
+    return 0
   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
+    if [ -d "$d" ]; then
+      install_to "$d" "$dry" || exit 1
+      installed=1
+    fi
   done
   if [ "$installed" = "0" ]; then
-    echo "未检测到项目级智能体目录。可用 --agent <name> / -g 装到用户级，或 --dir 指定。"
+    echo "目标错误: 未检测到项目级智能体目录。可用 --agent <name> 装到用户级，或用 --dir <路径> 指定目录。" >&2
+    exit 4
   fi
+  [ "$dry" = "1" ] || echo "完成。"
 }
 
-main "$@"
+main "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-intel",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Yuanqing — a zero-dependency threat-intel IOC extraction & normalization engine for AI agents: extracts IP (IPv4/IPv6), domains, URLs, emails, hashes (MD5/SHA1/SHA256/SHA512) and CVE IDs from threat reports, phishing emails and logs; recognizes and reverses defanged forms (hxxp / [.] / (.) / [dot] / [:] / [@]); deduplicates, normalizes (IDN punycode, default-port stripping) and outputs CSV / JSON / STIX-lite (STIX 2.1 Bundle) with the pure Python 3.8+ standard library. Triggers when the user provides text containing suspicious IPs / domains / URLs / hashes and needs IOC extraction, normalization, dedup, format conversion, or safe sharing. Boundaries: fully local and offline; no reputation lookups, no sample downloads, no proactive scanning; authorized / own-asset / educational use only.",
   "license": "MIT",
   "keywords": [

package/references/defang-rules.md

@@ -1,6 +1,6 @@
 # defang / refang 规则与共享建议
 
-> 元情 yotta-intel v0.2.0：去活性（defang）写法识别、还原与安全共享指引。
+> 元情 yotta-intel v0.2.1：去活性（defang）写法识别、还原与安全共享指引。
 
 ## 1. 为什么要 defang
 

package/references/ioc-spec.md

@@ -1,6 +1,6 @@
 # IOC 类型与判定规则（ioc-spec）
 
-> 元情 yotta-intel v0.2.0 内部规范：七类 IOC 的提取 / 归一 / 误报控制规则。
+> 元情 yotta-intel v0.2.1 内部规范：七类 IOC 的提取 / 归一 / 误报控制规则。
 > 本文件是引擎行为的权威说明；SKILL.md 只放入口，细节在这里。
 
 ## 1. 支持的类型

package/references/stix-lite-spec.md

@@ -1,6 +1,6 @@
 # STIX-lite 输出规范
 
-> 元情 yotta-intel v0.2.0：`extract --format stix` 的产物说明。
+> 元情 yotta-intel v0.2.1：`extract --format stix` 的产物说明。
 > 「lite」= 只生成 STIX 2.1 的 Indicator 对象 + 自定义扩展属性，不实现完整 STIX 库。
 
 ## 1. 为什么叫 lite

package/scripts/test_yotta_intel.py

@@ -488,7 +488,7 @@ class TestCLI(unittest.TestCase):
     def test_cli_version(self):
         r = run_cli("--version")
         self.assertEqual(r.returncode, 0)
-        self.assertIn("0.2.0", r.stdout)
+        self.assertIn("0.2.2", r.stdout)
 
     def test_cli_unknown_type_exit4(self):
         r = run_cli("extract", "--stdin", "--types", "bogus", stdin="1.2.3.4")

package/scripts/yotta_intel.py

@@ -52,7 +52,7 @@ try:
 except Exception:
     pass
 
-VERSION = "0.2.0"
+VERSION = "0.2.2"
 TOOL = "yotta-intel"
 TOOL_CN = "元情"
 
@@ -188,6 +188,23 @@ URL_RE = re.compile(r"(?i)(?:(?:https?|ftp)://)[^\s<>\"'，。！？；：、（
 EMAIL_RE = re.compile(r"(?i)[a-z0-9._%+\-]+@[a-z0-9\-]+(?:\.[a-z0-9\-]+)+")
 DOMAIN_RE = re.compile(r"(?<![\w@.])(?:[\w\-]{1,63}\.)+[\w\-]{2,63}(?![\-\w])")
 IPV4_RE = re.compile(r"(?<!\d)(?:\d{1,3}\.){3}\d{1,3}(?!\d)")
+
+
+def normalize_ipv4_octets(raw):
+    """把前导零写法（010.000.000.001）归一为 10.0.0.1。
+
+    Python 3.9.5 起 ipaddress.IPv4Address 拒绝前导零八位组，旧版本接受；
+    这里先做十进制归一，保证跨版本行为一致（999.1.1.1 仍会被判非法）。
+    """
+    parts = raw.split(".")
+    if len(parts) != 4:
+        return raw
+    out = []
+    for part in parts:
+        if not part.isdigit() or len(part) > 3:
+            return raw
+        out.append(str(int(part)))
+    return ".".join(out)
 IPV6_TOKEN_RE = re.compile(r"(?i)(?<![\w:])(?:[0-9a-f:.]{2,45})(?![\w:])")
 HASH_RE = re.compile(r"(?i)(?<![0-9a-f])[0-9a-f]{32,128}(?![0-9a-f])")
 CVE_RE = re.compile(r"(?i)\bcve-\d{4}-\d{4,7}\b")
@@ -287,7 +304,7 @@ def find_iocs_in_line(line):
     for m in IPV4_RE.finditer(line):
         raw = m.group(0)
         try:
-            ip = ipaddress.IPv4Address(raw)
+            ip = ipaddress.IPv4Address(normalize_ipv4_octets(raw))
         except ValueError:
             continue
         found.append((m.start(), m.end(), "ipv4", str(ip)))