@yottameta/yotta-guardian 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # 更新日志
 
+## v0.1.8 (2026-10-01)
+
+- 安装器卫生批次：`bin/install.js` / `install.sh` 统一（未知参数报错 exit 2、`--help` / `--version`、残留清理白名单、嵌套载荷保留）；由模板单一真源渲染，接入漂移门禁。
+
+## v0.1.7 (2026-09-28)
+
+文档格式修复 + 两处引擎健壮性修复（规则判定行为不变）。
+
+- **修复代码围栏**：`SKILL.md` 与 `references/`（intent-verifier / policies / rules）中被写作管线占位符顶替的代码围栏，全部还原为标准三个反引号，共 20 处；此前自 0.1.0 起一直未还原，Markdown 渲染异常（命令与配置示例无法按代码块显示）。
+- **修复非法转义（0.1.0 起既有）**：`scripts/guardian_rules.py` 的模块 docstring 里 `\s`、`\b` 属非法转义 —— Python 3.12+ 每次调用都向 stderr 报 2 行 SyntaxWarning，严格告警（`PYTHONWARNINGS=error`）下引擎直接加载失败。该 docstring 改为 raw 字符串（与规则表内 `r"…"` 写法一致），告警消失。
+- **修复致命异常退出码（fail-closed，0.1.0 起既有）**：此前未捕获异常走 Python 默认退出码 1，而契约里 1 = 允许但带警告 —— 按退出码判定的宿主会把「引擎崩溃」读成放行（fail-open）。现在规则表加载失败与运行期未预期异常统一以**退出码 4**（用法错误 / 致命异常）结束并在 stderr 写明原因；新增 3 项回归用例（导入失败 → 4、运行期异常 → 4、严格告警下仍正常判定，共 86 项）。
+- **修复彩色输出必崩（0.1.6 起既有）**：`check` 的彩色分支 `c()` 格式串只有 1 个 `%s` 却喂 2 个参数 —— 真人终端（`sys.stdout.isatty()` 为真）必抛 `TypeError`，以退出码 4 结束且**判定与命中规则完全不输出**；`--json` / `--no-color` / 管道不受影响（故此前测试未覆盖）。已修正格式串，并新增「假 TTY」回归用例（共 88 项）。
+- **文档**：`SKILL.md` 新增「宿主接入」一节（放行不代批 / 用文件接引擎输出 / stdin 按 UTF-8 读），并把退出码 4 的语义写成「用法错误 / 致命异常（绝不要当作放行）」。
+- **发布门禁联动**：`validate-skill` 与 `preflight-publish` 的交付面检查扩到 Python 一侧（语法错误 / 非法转义等编译期告警），与 Markdown 检查共用同一入口，命中即拦。
+- 规则判定、策略档位、CLI 输出结构与审计格式不变；版本四处对齐 0.1.7。
+
 ## v0.1.6 (2026-09-25)
 
 安全修复：复合命令拆分，堵住分隔符后的危险段绕过。
@@ -50,7 +66,7 @@
 
 - **README.md 改为英文**：作为 GitHub / npm / ClawHub 首页的英文门面（翻译 + 精简，覆盖定位 / 核心价值 / 命令 / 快速使用 / 安装 / 使用示例 / 边界 / 开发校验全流程）。
 - **新增 README.zh-CN.md**：原中文完整主文档整体平移，顶部加语言切换链接。
-- **修复代码围栏**：README 中 `_BT_`bash / `_BT_` 占位符全部改为标准 ```bash / ```（Markdown 渲染修复）。
+- **修复代码围栏**：README 中的围栏占位符（写作管线留下的标记）全部改为标准 ```bash / ```（Markdown 渲染修复）。
 - **package.json**：description 改英文；files 加 README.zh-CN.md；版本 0.1.0 → 0.1.1。
 - 版本四处对齐：package.json / SKILL frontmatter / 引擎 VERSION / 文档。
 - 边界（B 方案）：references / CHANGELOG / 测试注释不翻译；SKILL 触发描述保持中文。

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yotta-guardian
-version: 0.1.6
+version: 0.1.8
 description: 元盾 —— 跨智能体的危险调用拦截护栏：确定性规则引擎 + 可插拔意图验证（不绑模型），拦截危险 exec / write / edit / read / run / shell 工具调用，提供审计日志。触发：代理要执行高风险命令（递归删除、磁盘格式化、提权、防火墙改动、反向 shell、下载即执行等）、要写入系统敏感路径或修改系统配置、要在执行危险操作前做安全检查、或用户说 护栏/拦截/危险操作/安全检查 等。边界：默认只读评估，不自动执行也不放行危险操作；不替代用户决策；不隐藏审计记录；规则可配置。
 license: MIT
 ---
@@ -27,7 +27,7 @@ license: MIT
 
 Windows 用 python，Linux/macOS 用 python3。
 
-`_BT_`bash
+```bash
 # 检查一条 exec（0 = 允许）
 python3 scripts/yotta_guardian.py check exec --cmd "git status"
 
@@ -43,15 +43,25 @@ python3 scripts/yotta_guardian.py check --batch calls.json --json
 # 审计
 python3 scripts/yotta_guardian.py check exec --cmd "..." --audit-log .yotta-guardian/audit.jsonl
 python3 scripts/yotta_guardian.py audit --file .yotta-guardian/audit.jsonl --tail 20
-`_BT_`
+```
 
 ## 工作流程（AI 智能体执行危险操作前）
 
 1. **先检查**：把将要执行的工具调用交给护栏 `check`（单条或 `--batch` 批量）。
-2. **看退出码**：0 = 允许；1 = 允许但带警告（建议人工复核）；2 / 3 = 拒绝（high / critical，不要执行）；4 = 用法错误。
+2. **看退出码**：0 = 允许；1 = 允许但带警告（建议人工复核）；2 / 3 = 拒绝（high / critical，不要执行）；4 = 用法错误 / 致命异常（引擎没跑起来 —— 绝不要当作放行）。
 3. **被拒绝怎么办**：如实向用户报告原因与命中规则；确有授权的操作，用 `--allow` / `--allow-path` / 自定义规则文件放行并留审计记录；**不要绕过检查**。
 4. **留痕**：高风险场景用 `--audit-log` 落审计日志，供追溯。
 
+## 宿主接入（把护栏挂到「工具调用前」事件时）
+
+`skill-manifest.json` 声明 `before_tool` + `fallback: explicit-unverified`。接入方按下面三条做，可避开实测踩过的坑：
+
+1. **放行不要回「允许」**：只在拦截时输出拒绝判定（如 `permissionDecision: "deny"`）；放行时**不输出任何判定**，把决定权交回宿主。若放行时回「allow」，会覆盖宿主自身的权限流程，护栏就变成自动放行器 —— 护栏只该「拦」，不该「代批」。
+2. **用文件接引擎输出**：部分 hook 进程环境里，用管道捕获子进程 stdout 会拿到空值（同一写法跑 `python -c "print(1)"` 却正常）；把引擎 stdout / stderr 重定向到临时文件再读回，判定即稳定（引擎自身的 stdout 是纯净的，`--json` 可直接解析）。
+3. **stdin 先按 UTF-8 读**：hook 载荷里的命令文本常含中文，按本机默认码页解码会乱码；读 stdin 前先 `sys.stdin.reconfigure(encoding="utf-8")`（引擎已对自身 stdout / stderr 做 UTF-8 处理，stdin 由接入方负责）。
+
+另外：引擎对「没跑起来」是 fail-closed 的 —— 规则表加载失败或运行期未预期异常一律以退出码 4 结束并在 stderr 写「致命异常: …」。接入方应把 4 当作**不放行 + 报告**处理，而不是放行。
+
 ## 策略（policy）
 
 | 策略 | 行为 |

package/bin/install.js

@@ -1,12 +1,18 @@
 #!/usr/bin/env node
 /**
  * yotta-guardian 跨平台安装器（YottaSkills）
+ *
  * 用法:
- *   npx -y @yottameta/yotta-guardian --agent <name>  # 按智能体默认用户级目录安装（推荐）
- *   npx -y @yottameta/yotta-guardian --dir PATH      # 装到指定目录（用户改了目录的智能体）
- *   npx -y @yottameta/yotta-guardian -g              # 安装到全部已知智能体用户级目录
- *   npx -y @yottameta/yotta-guardian                 # 安装到检测到的项目级目录
- *   npx -y @yottameta/yotta-guardian --list          # 列出智能体 -> 默认目录
+ *   npx -y @yottameta/yotta-guardian --agent <name>   # 按智能体默认用户级目录安装（推荐）
+ *   npx -y @yottameta/yotta-guardian --dir <path>     # 装到指定目录（用户改了目录的智能体）
+ *   npx -y @yottameta/yotta-guardian -g               # 安装到全部已知智能体用户级目录
+ *   npx -y @yottameta/yotta-guardian                  # 安装到检测到的项目级目录
+ *   npx -y @yottameta/yotta-guardian --list           # 列出智能体 -> 默认目录
+ *   npx -y @yottameta/yotta-guardian --dry-run        # 只显示将写入的目标，不写文件
+ *   npx -y @yottameta/yotta-guardian --version        # 显示版本
+ *   npx -y @yottameta/yotta-guardian --help           # 显示帮助
+ *
+ * 退出码: 0 成功 / 1 安装失败 / 2 用法错误 / 4 目标错误
  */
 'use strict';
 const fs = require('fs');
@@ -16,6 +22,21 @@ const os = require('os');
 const SKILL_NAME = 'yotta-guardian';
 const PKG_ROOT = path.join(__dirname, '..');
 
+// 顶层开发文件 / 目录：只在安装包顶层跳过；技能包内嵌套同名载荷必须保留。
+// 与 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。
@@ -39,6 +60,26 @@ const AGENT_DIRS = {
   agents:    { label: '通用 AGENTS.md',    dirs: ['.agents/skills'] },
 };
 
+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');
@@ -57,107 +98,239 @@ 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 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(SKILL_NAME + ' 安装器（YottaSkills）');
+  console.log('');
+  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('参数:');
+  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, 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 需要一个非空路径');
+      opts.dir = value;
+    } else if (arg === '--agent') {
+      const value = argv[++i];
+      if (!value) throw new UsageError('--agent 需要一个非空名称');
+      opts.agent = String(value).toLowerCase();
+    } else {
+      throw new UsageError('未知参数: ' + arg);
+    }
+  }
+  if (!opts.help && !opts.version) {
+    const selected = [opts.dir, opts.agent, opts.global].filter(Boolean).length;
+    if (selected > 1) throw new UsageError('--dir / --agent / -g 只能选一个');
+  }
+  return opts;
+}
+
+function printList() {
+  console.log('智能体 -> 默认技能目录（--agent <name> 装到第一个，用户级）:');
+  for (const [key, value] of Object.entries(AGENT_DIRS)) {
+    const resolved = value.dirs.map(displayDir);
+    console.log('  ' + key.padEnd(10) + value.label.padEnd(18) + resolved.join('、'));
+  }
+  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('目标目录不能在技能源目录内（防止自装自毁）');
+  }
 }
 
-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;
+    // 只跳过安装包顶层开发文件；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, skip);
+      copyDir(s, d, false);
     } else if (entry.isFile()) {
       fs.copyFileSync(s, d);
     }
   }
 }
 
-function displayDir(rel) {
-  if (process.platform === 'win32') return '%USERPROFILE%\\' + rel.replace(/\//g, '\\');
-  return '~/' + rel;
+// 清理旧版安装残留（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()) {
+        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));
+      }
+    }
+  };
+  walk(target);
+  return removed;
 }
 
-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('、'));
+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, true);
+    if (!fs.existsSync(path.join(target, 'SKILL.md'))) {
+      throw new InstallError('安装结果缺少 SKILL.md');
+    }
+  } catch (err) {
+    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 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('\n说明：Windows 用 %USERPROFILE%，Linux/macOS 用 ~；仅收录有官方默认目录的智能体。');
-    console.log('改了目录的请用 --dir <路径>，不要依赖默认位置；若设置了 CODEX_HOME / XDG_CONFIG_HOME，安装自动以该变量为准。');
+    console.log(SKILL_NAME + ' v' + version);
     return;
   }
+  if (opts.list) { printList(); return; }
 
-  if (explicitDir) { installTo(explicitDir); return; }
+  if (opts.dir) { installTo(opts.dir, opts); return; }
 
-  if (agent) {
-    const info = AGENT_DIRS[agent];
+  if (opts.agent) {
+    const info = AGENT_DIRS[opts.agent];
     if (!info) {
-      console.log('未收录智能体: ' + agent + '。请用 --dir <路径> 指定技能目录。');
-      console.log('可用: ' + Object.keys(AGENT_DIRS).join(', '));
-      return;
+      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 (isGlobal) {
+  if (opts.global) {
     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));
+    for (const value of Object.values(AGENT_DIRS)) {
+      for (const rel of value.dirs) {
+        if (seen.has(rel)) continue;
+        seen.add(rel);
+        installTo(resolveUserDir(rel), opts);
       }
     }
-    console.log('完成。');
+    if (!opts.dryRun) 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; }
+  const dirs = PROJECT_DIRS.filter((d) => fs.existsSync(d));
+  if (!dirs.length) {
+    throw new TargetError('未检测到项目级智能体目录。可用 --agent <name> 装到用户级，或用 --dir <路径> 指定目录。');
   }
-  if (!installedAny) {
-    console.log('未检测到项目级智能体目录。可手动复制，或用 --agent <name> / -g 装到用户级。');
+  for (const dir of dirs) installTo(dir, opts);
+  if (!opts.dryRun) console.log('完成。');
+}
+
+function main() {
+  try {
+    run();
+  } catch (err) {
+    if (err instanceof UsageError) {
+      console.error('用法错误: ' + err.message);
+      usage();
+      process.exitCode = 2;
+    } else if (err instanceof TargetError) {
+      console.error('目标错误: ' + err.message);
+      process.exitCode = 4;
+    } else if (err instanceof InstallError) {
+      console.error('安装失败: ' + err.message);
+      console.error('修复建议: 检查目录权限与磁盘空间后重试，或用 --dir 换一个目录。');
+      process.exitCode = 1;
+    } else {
+      console.error('未知错误: ' + (err && err.message ? err.message : String(err)));
+      process.exitCode = 1;
+    }
   }
 }
 
-main();
+main();

package/install.sh

@@ -1,28 +1,30 @@
 #!/usr/bin/env bash
-# yotta-guardian 多智能体安装脚本（YottaSkills 模板）
+# yotta-guardian 多智能体安装脚本（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-guardian"
 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,36 +62,153 @@ resolve_user() {
   esac
 }
 
-install_to() {
-  local base="$1"
-  local dest
-  case "$base" in
-    ""|"/") echo "安装失败：拒绝不安全的目标目录：'$base'" >&2; return 1 ;;
+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() {
+  local base="$1" dry="$2" dest
+  dest="$base/$SKILL_NAME"
   if [ -L "$base" ]; then
-    echo "安装失败：目标目录是符号链接，拒绝跟随：$base" >&2; return 1
+    echo "安装失败：目标目录是符号链接，拒绝跟随：$base" >&2
+    return 1
+  fi
+  if [ -e "$base" ] && [ ! -d "$base" ]; then
+    echo "安装失败：目标路径已存在且不是目录：$base" >&2
+    return 1
   fi
-  mkdir -p "$base"
-  dest="$base/$SKILL_NAME"
   if [ -L "$dest" ]; then
-    echo "安装失败：技能目录是符号链接，拒绝跟随：$dest" >&2; return 1
+    echo "安装失败：技能目录是符号链接，拒绝跟随：$dest" >&2
+    return 1
   fi
   if [ -e "$dest" ] && [ ! -d "$dest" ]; then
-    echo "安装失败：技能路径已存在且不是目录：$dest" >&2; return 1
-  fi
-  mkdir -p "$dest"
-  cp -RP "$SOURCE_DIR/." "$dest/"
-  # 只清理副本内部的开发残留（固定子路径），不做整目录删除、不跟随符号链接
-  if [ -d "$dest/.git" ] && [ ! -L "$dest/.git" ]; then rm -rf "$dest/.git"; fi
-  find "$dest" -type d -name '__pycache__' -prune -exec rm -rf {} + 2>/dev/null || true
-  find "$dest" -type f -name '*.pyc' -delete 2>/dev/null || true
+    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
@@ -108,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 "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-guardian",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Yuandun (元盾) — cross-agent dangerous tool-call guardrail: a deterministic rule engine + pluggable intent verifier (model-agnostic) that evaluates exec/write/edit/read/run/shell calls and provides audit logs. Triggers when an agent is about to run a high-risk command, write sensitive paths, or change system config. Boundaries: read-only evaluation by default, configurable allowances.",
   "license": "MIT",
   "keywords": [

package/references/intent-verifier.md

@@ -13,7 +13,7 @@
 
 引擎对「允许」结论的调用发起验证，写入 stdin 的 JSON：
 
-`_BT_`json
+```json
 {
   "tool": "exec",
   "cmd": "npm install",
@@ -24,19 +24,19 @@
   "cwd": "/home/user/project",
   "findings": []
 }
-`_BT_`
+```
 
 字段说明：tool 为工具类型；cmd / path / content_preview（内容前 500 字符）/ target 为调用内容；policy 为当前策略；findings 为确定性规则已命中的条目（允许结论下通常为空或仅低危）。
 
 ## 三、响应（stdout，JSON）
 
-`_BT_`json
+```json
 {
   "verdict": "allow",
   "severity": "low",
   "reason": "安装依赖，无恶意信号"
 }
-`_BT_`
+```
 
 - verdict：allow / deny / review 三选一（必须）。
 - severity：可选，deny 时默认 high；取值 info / low / medium / high / critical。
@@ -59,7 +59,7 @@
 
 ## 六、示例验证器（Python 桩）
 
-`_BT_`python
+```python
 #!/usr/bin/env python3
 import json
 import sys
@@ -71,6 +71,6 @@ if cmd.startswith("danger"):
 else:
     out = {"verdict": "allow", "severity": "low", "reason": "无风险信号"}
 json.dump(out, sys.stdout)
-`_BT_`
+```
 
 真实场景可用该协议把调用摘要发给 LLM 网关做语义判断，返回同样的 JSON 即可接入。

package/references/policies.md

@@ -34,9 +34,9 @@ AI 智能体判断：退出码非 0 时不要直接执行；2 / 3 一律停下
 
 ### 执行前 gate
 
-`_BT_`bash
+```bash
 python3 scripts/yotta_guardian.py check exec --cmd "<待执行命令>" --json
-`_BT_`
+```
 
 - exit 0：执行。
 - exit 1：执行但提示用户「护栏给出中危警告」。
@@ -45,9 +45,9 @@ python3 scripts/yotta_guardian.py check exec --cmd "<待执行命令>" --json
 
 ### 批量预检
 
-`_BT_`bash
+```bash
 python3 scripts/yotta_guardian.py check --batch calls.json --json
-`_BT_`
+```
 
 calls.json 为数组或 {"calls": [...]}，每项含 tool / cmd / path / content / old / new / target。任一被拒时整体退出码取最严重值。
 
@@ -55,25 +55,25 @@ calls.json 为数组或 {"calls": [...]}，每项含 tool / cmd / path / content
 
 确有授权的操作（如正规重启、备份清理）用显式放行，而不是绕过检查：
 
-`_BT_`bash
+```bash
 python3 scripts/yotta_guardian.py check exec --cmd "<命令>" --allow "<模式>"
 python3 scripts/yotta_guardian.py check write --path "<路径>" --allow-path "<前缀>"
-`_BT_`
+```
 
 ### 审计
 
-`_BT_`bash
+```bash
 # 检查时落审计
 python3 scripts/yotta_guardian.py check exec --cmd "<命令>" --audit-log .yotta-guardian/audit.jsonl
 
 # 查询
 python3 scripts/yotta_guardian.py audit --file .yotta-guardian/audit.jsonl --tail 20
 python3 scripts/yotta_guardian.py audit --file .yotta-guardian/audit.jsonl --denied --json
-`_BT_`
+```
 
 ## 五、JSON 输出结构（check --json）
 
-`_BT_`json
+```json
 {
   "tool": "yotta-guardian",
   "version": "0.1.0",
@@ -93,4 +93,4 @@ python3 scripts/yotta_guardian.py audit --file .yotta-guardian/audit.jsonl --den
     }
   ]
 }
-`_BT_`
+```

package/references/rules.md

@@ -101,7 +101,7 @@
 
 ## 六、自定义规则文件（--config）
 
-`_BT_`json
+```json
 {
   "policy": "default",
   "allow": ["^git "],
@@ -109,7 +109,7 @@
   "deny": ["^evil"],
   "verifier": { "command": ["python3", "/path/verifier.py"], "timeout": 30 }
 }
-`_BT_`
+```
 
 - policy: default / strict / loose
 - allow: 命令正则放行模式

package/scripts/guardian_rules.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""guardian_rules.py — YottaMeta 元盾（yotta-guardian）内置规则表（数据，不含匹配逻辑）。
+r"""guardian_rules.py — YottaMeta 元盾（yotta-guardian）内置规则表（数据，不含匹配逻辑）。
 
 本文件只声明规则数据，与 yotta-security-audit（元安）/ yotta-vetter（元审）的
 「源码静态扫描」规则不同：这里是「工具调用护栏」规则，面向 exec / write / edit 等

package/scripts/yotta_guardian.py

@@ -49,9 +49,15 @@ except Exception:
 
 _HERE = Path(__file__).resolve().parent
 sys.path.insert(0, str(_HERE))
-import guardian_rules as GR  # noqa: E402
+try:
+    import guardian_rules as GR  # noqa: E402
+except BaseException as _import_exc:  # 规则表加载失败 = 引擎没跑起来 → 致命异常（4）
+    sys.stderr.write(
+        "致命异常: 规则表加载失败: %s: %s\n" % (type(_import_exc).__name__, _import_exc)
+    )
+    raise SystemExit(4)
 
-VERSION = "0.1.6"
+VERSION = "0.1.8"
 TOOL_NAME = "yotta-guardian"
 TOOL_CN = "元盾"
 
@@ -1138,7 +1144,8 @@ def _build_verifier(args):
 
 def _print_check_text(call, verdict, color):
     def c(s, code):
-        return "\033[%sm\033[0m" % (code, s) if color else s
+        # 2026-09-28：原写法只有 1 个 %s 却喂了 2 个参数 → 彩色路径（真人终端）必崩 TypeError。
+        return "\033[%sm%s\033[0m" % (code, s) if color else s
     kind = c("DENY", "31;1") if not verdict.allowed else c("ALLOW", "32;1")
     sev = verdict.severity.upper()
     print("[检查]  %s" % call.describe(300))
@@ -1367,4 +1374,16 @@ def main(argv=None):
 
 
 if __name__ == "__main__":
-    main()
+    # 顶层兜底（2026-09-28）：未捕获异常一律按「致命异常」退出码 4 结束。
+    # 绝不能让引擎崩溃落到 1 —— 契约里 1 = 允许但带警告，按退出码判定的宿主会把
+    # 「护栏没跑起来」读成放行（fail-open）。SystemExit / KeyboardInterrupt 原样透传。
+    try:
+        main()
+    except (SystemExit, KeyboardInterrupt):
+        raise
+    except BaseException as exc:  # 兜底就是要 catch-all
+        try:
+            sys.stderr.write("致命异常: %s: %s\n" % (type(exc).__name__, exc))
+        except Exception:
+            pass
+        raise SystemExit(4)

package/skill-manifest.json

@@ -3,7 +3,7 @@
   "slug": "yotta-guardian",
   "name": "元盾",
   "package": "@yottameta/yotta-guardian",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "trust": "yottameta",
   "install": {
     "idempotent": true