@yottameta/yotta-intel 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 更新日志
 
+## v0.2.0 (2026-09-09)
+
+- 评测完善批 2：新增 references/faq.md（12 条常见问题 + 速查索引 + 安装排障）；SKILL.md 增加 FAQ 速查节。
+- 安装器错误处理：用法/目标/安装错误统一退出码与修复建议；新增 test/install.test.js。
+- package.json 补 npm test 脚本；版本对齐 0.2.0（package / SKILL / CHANGELOG / CLI）。
+
 ## v0.1.1 (2026-08-29)
 
 - 安装方式统一为四方式（对齐发布规范 §3.3.1）：方式一 `npx -y @yottameta/yotta-intel --agent <name>` / `--dir <dir>`（推荐，走 npm 源）；方式二 `git clone https://github.com/YottaMeta/yotta-intel.git`；方式三 GitHub Download ZIP；方式四 `bash install.sh --agent/--dir/--list`。移除 `npx skills` 与 `-g` 推荐；中英双 README 安装节同步。
@@ -19,4 +25,4 @@
 - 误报控制：域名 TLD 白名单 + 文件名过滤（README.md / test.py 不算域名）+ 中文标点截断 + 哈希长度校验。
 - 四种输出：text / JSON / CSV / STIX-lite（STIX 2.1 Bundle + indicator pattern，uuid5 确定性）。
 - 测试：103 个用例全绿；含 CLI 端到端（stdin / 文件 / 退出码）。
-- 文档：SKILL.md + README 中英双版 + references（ioc-spec / defang-rules / stix-lite-spec）。
+- 文档：SKILL.md + README 中英双版 + references（ioc-spec / defang-rules / stix-lite-spec）。

package/LICENSE

@@ -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/NOTICE

@@ -8,4 +8,4 @@
 2. 不得暗示派生作品由 YottaMeta 官方维护、认可或与之存在关联；
 3. 建议在派生作品中明确声明「与 YottaMeta 官方无关联」。
 
-上游来源致谢：本技能由 YottaMeta 全新实现（零依赖自研 + 中文教学），威胁情报 IOC 提取 / defang / STIX 映射方向参考开源社区 threat-intelligence / IOC-extraction 类技能思路，无上游代码。
+上游来源致谢：本技能由 YottaMeta 全新实现（零依赖自研 + 中文教学），威胁情报 IOC 提取 / defang / STIX 映射方向参考开源社区 threat-intelligence / IOC-extraction 类技能思路，无上游代码。

package/README.md

@@ -91,7 +91,7 @@ python3 scripts/yotta_intel.py refang --path safe.txt
 Sample text output:
 
 ```
-元情 yotta-intel v0.1.1 —— IOC 提取结果
+元情 yotta-intel v0.2.0 —— IOC 提取结果
 共发现 2 个 IOC：
 
 ■ IPv4 地址（ipv4）

package/README.zh-CN.md

@@ -25,7 +25,7 @@
 ## 这是什么
 
 威胁情报分析经常从「一堆文本里找指标」开始：这份报告里有哪些可疑 IP？钓鱼邮件里的域名 / 链接是什么？
-样本哈希是多少、属于哪种算法？元情把这些能力打包成零依赖引擎——不需要 MISP / OpenCTI / 商业情报平台，
+样本哈希是多少、属于哪种算法？元情把这些能力打包成零依赖引擎——不需要 MISP / OpenCTI / 厂商情报平台，
 用纯 Python 标准库就能完成 IOC 提取、defang/refang、去重、归一化与格式转换。
 
 它不是任何单一平台的专属工具：它是一套与智能体无关的工具包，任何支持 Agent Skills 的智能体都能用。
@@ -99,7 +99,7 @@ python3 scripts/yotta_intel.py refang --path safe.txt
 输出示例（text）：
 
 ```
-元情 yotta-intel v0.1.1 —— IOC 提取结果
+元情 yotta-intel v0.2.0 —— IOC 提取结果
 共发现 2 个 IOC：
 
 ■ IPv4 地址（ipv4）

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yotta-intel
-version: 0.1.1
+version: 0.2.0
 description: 元情 —— 跨智能体的威胁情报 IOC 提取与规范化技能：零依赖自研从文本 / 日志 / 报告中提取 IP（IPv4/IPv6）、域名、URL、邮箱、哈希（MD5/SHA1/SHA256/SHA512）与 CVE 编号，识别并还原 defang 写法，去重、归一化后输出 CSV / JSON / STIX-lite。触发：用户给出含可疑 IP / 域名 / URL / 哈希的威胁情报文本、恶意样本分析报告、钓鱼邮件或日志，要提取 IOC、规范化、去重、转格式、共享情报时。边界：纯本地离线提取与规范化；不联网查证、不下载样本、不主动扫描任何系统；仅用于已获授权 / 自有资产 / 教学环境的安全分析。
 license: MIT
 ---
@@ -110,7 +110,11 @@ defang / refang 成功均为 **0**。
 - references/defang-rules.md — defang / refang 规则与安全共享建议
 - references/stix-lite-spec.md — STIX-lite 输出规范与 pattern 映射
 
+## 常见问题（速查）
+
+装不上、提取为空、defang 没还原、退出码看不懂时，先看 references/faq.md（含速查索引与安装排障）。
+
 ## 法律声明
 
 本技能仅用于**已获明确授权**的安全分析（自有资产、授权测试、CTF 靶场、教学环境）。
-未经授权分析他人系统数据违反中国《网络安全法》与《刑法》相关条款，使用者自行承担法律责任。
+未经授权分析他人系统数据违反中国《网络安全法》与《刑法》相关条款，使用者自行承担法律责任。

package/bin/install.js

@@ -1,163 +1,245 @@
-#!/usr/bin/env node
-/**
- * yotta-intel 跨平台安装器（YottaSkills）
- * 用法:
- *   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          # 列出智能体 -> 默认目录
- */
-'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, '..');
-
-// 智能体 -> 用户级默认技能目录（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();
+#!/usr/bin/env node
+/**
+ * @yottameta/yotta-intel cross-platform installer.
+ *
+ * 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
+ */
+'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']);
+
+const AGENT_DIRS = {
+  claude:    { label: 'Claude Code',      dirs: ['.claude/skills'] },
+  cursor:    { label: 'Cursor',           dirs: ['.cursor/skills', '.agents/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'] },
+  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: 'Generic AGENTS.md', dirs: ['.agents/skills'] },
+};
+
+class UsageError extends Error {}
+class TargetError extends Error {}
+class InstallError extends Error {}
+
+function usage() {
+  console.log('yotta-intel installer');
+  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('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');
+}
+
+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:');
+  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.');
+}
+
+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');
+  }
+}
+
+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);
+    }
+  }
+}
+
+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');
+    }
+  } 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;
+}
+
+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.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 (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();

package/install.sh

@@ -1,132 +1,132 @@
-#!/usr/bin/env bash
-# yotta-intel 多智能体安装脚本（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-intel"
-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-intel 多智能体安装脚本（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-intel"
+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

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-intel",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "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": [
@@ -18,7 +18,10 @@
     "assets",
     "bin",
     "NOTICE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "!scripts/__pycache__",
+    "!**/__pycache__",
+    "!**/*.pyc"
   ],
   "repository": {
     "type": "git",
@@ -29,5 +32,8 @@
   },
   "bin": {
     "yotta-intel": "bin/install.js"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.js\" && python scripts/test_yotta_intel.py"
   }
-}
+}

package/references/defang-rules.md

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

package/references/faq.md

@@ -0,0 +1,58 @@
+# 元情常见问题
+
+## 速查索引
+
+- **提取**：为什么没提出 IOC · 哈希为什么漏了 · 域名为什么误报
+- **格式**：defang 没还原 · CSV/JSON 怎么选 · STIX 怎么用
+- **报错**：文件读不了 · 退出码是什么意思
+- **安装**：装到哪个目录 · 和元钥/元察怎么分工
+
+---
+
+## 1. 为什么文本里有地址却一个 IOC 都没提取？
+
+先确认文本是普通报告、钓鱼邮件还是日志：纯文本用 `extract --path`，管道内容用 `extract --stdin`。若原文被 `[.]`、`hxxp` 等去活性写法包裹，`extract` 会先做 refang 预处理，理论上也能命中；仍为空时可先用 `refang` 看还原结果，再检查 IOC 是否属于被类型过滤或 `--min-count` 过滤的范围。
+
+## 2. 提取结果把 `README.md`、`test.py` 当域名了？
+
+不会。引擎对常见的文件名后缀（`.md`、`.py`、`.sh` 等）做了过滤，也要求域名至少两级且 TLD 在白名单内；单标签、纯数字 TLD 都会被拒绝。
+
+## 3. 为什么某些 32/40 位十六进制没有被当哈希？
+
+哈希必须满足长度且不能被识别为 UUID 等其它格式；若十六进制串嵌在普通句子或代码里，可能被当作普通 token 跳过。要确认某段是否真的是哈希，可以把它单独放一行或用 `verify` 类工具复核；本引擎只提取明确形态。
+
+## 4. defang 文本没有被还原？
+
+先确认写法是否属于支持的形态：`[.]`、`(.)`、`[dot]`、`hxxp`、`[@]`、`[:]`、`[/]` 等均支持；大小写不敏感。若用了自定义分隔符（如 ` DOT `、URL 编码），引擎不会猜测，需先还原成标准形态。
+
+## 5. CSV、JSON、STIX 怎么选？
+
+给表格/平台导入用 CSV；给程序或自动化下游用 JSON（结构完整、含来源与行号）；要生成 STIX 2.1 Bundle 供 SIEM 或情报平台导入用 `--format stix`。
+
+## 6. STIX 输出和 JSON 里的 IOC 数量为什么可能不同？
+
+JSON/CSV 会保留去重后的七类 IOC；STIX-lite 也按同源生成 indicator，字段以规范文档为准。若你在 STIX 里看不到某类型，先检查该类型是否被 `--types` 过滤或引擎判定为无效格式。
+
+## 7. 提示文件不存在/读取失败，退出码是什么？
+
+文件不存在、无输入、未知类型等用法或读取错误统一为退出码 4；`extract` 成功但未发现 IOC 为 0，发现 IOC 为 1。`--stdin` 模式请确保确实有管道输入。
+
+## 8. 可以传目录吗？
+
+`extract` 面向单文件或 stdin；要批量处理目录请由 AI 遍历文件后逐个提取，或在脚本里对每个文件调用一次。`defang/refang` 同样按单文件/流处理。
+
+## 9. 输出里 `count` 和 `first_line` 怎么理解？
+
+`count` 是同一 IOC 在文本中出现的次数；`first_line` 是首次出现的行号；`snippet` 是上下文片段。用 `--min-count 2` 可过滤只出现一次的噪音。
+
+## 10. 我能在邮件/群聊里直接分享原始 IOC 吗？
+
+建议先 defang。原始 URL/邮箱/域名可能被平台自动转成可点击链接，误触或触发沙箱外联；`defang` 会保留可读性并去掉活性。
+
+## 11. 安装不上/智能体没识别怎么办？
+
+用 `npx -y @yottameta/yotta-intel --agent <名称>` 装到已知智能体，或 `--dir <技能目录>` 装到自定义路径；未收录智能体不要靠猜目录，直接 `--dir`。若走 npm 镜像遇到传播延迟，临时加 `--registry=https://registry.npmjs.org/`。
+
+## 12. 元情和元钥、元察怎么分工？
+
+元情只做威胁情报文本里的 IOC 提取/归一/格式转换；元钥负责源码/配置里的密钥泄露扫描；元察负责安全日志检测。输入是报告/邮件/日志文本时优先元情，输入是代码/配置仓库时用元钥。

package/references/ioc-spec.md

@@ -1,6 +1,6 @@
 # IOC 类型与判定规则（ioc-spec）
 
-> 元情 yotta-intel v0.1.1 内部规范：七类 IOC 的提取 / 归一 / 误报控制规则。
+> 元情 yotta-intel v0.2.0 内部规范：七类 IOC 的提取 / 归一 / 误报控制规则。
 > 本文件是引擎行为的权威说明；SKILL.md 只放入口，细节在这里。
 
 ## 1. 支持的类型
@@ -63,4 +63,4 @@
 
 - 纯本地离线：不联网查证、不下载样本、不主动扫描任何系统；只做文本提取与规范化。
 - 提取结果只是「候选指标」，是否恶意需人工 / 其他情报源核实；本引擎不给恶意定性。
-- 仅用于已获授权 / 自有资产 / 教学环境的安全分析。
+- 仅用于已获授权 / 自有资产 / 教学环境的安全分析。

package/references/stix-lite-spec.md

@@ -1,6 +1,6 @@
 # STIX-lite 输出规范
 
-> 元情 yotta-intel v0.1.1：`extract --format stix` 的产物说明。
+> 元情 yotta-intel v0.2.0：`extract --format stix` 的产物说明。
 > 「lite」= 只生成 STIX 2.1 的 Indicator 对象 + 自定义扩展属性，不实现完整 STIX 库。
 
 ## 1. 为什么叫 lite
@@ -73,4 +73,4 @@ pattern 内使用原始规范值（机器可解析）；人看的 defang 形态
 - **共享**：与报告一起发时，把 `defanged` 列给读者看，把 STIX 文件给机器用。
 - **人工核对**：`labels` 是默认值，接入生产情报库前应由分析师复核并补充 Confidence / 来源。
 - **升级提示**：本输出是 lite 子集，不含 Sighting / Relationship / Kill Chain；需要完整图谱时
-  请用专业 STIX 工具链。
+  请用专业 STIX 工具链。

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.1.1", r.stdout)
+        self.assertIn("0.2.0", 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.1.1"
+VERSION = "0.2.0"
 TOOL = "yotta-intel"
 TOOL_CN = "元情"