npm - @yottameta/yotta-guardian - Versions diffs - 0.1.1 → 0.1.2 - Mend

@yottameta/yotta-guardian 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,11 @@
 # 更新日志
+## v0.1.2 (2026-08-29)
+- 安装方式统一为四方式（对齐发布规范 §3.3.1）：方式一 `npx -y @yottameta/yotta-guardian --agent <name>` / `--dir <dir>`（推荐，走 npm 源）；方式二 `git clone https://github.com/YottaMeta/yotta-guardian.git`；方式三 GitHub Download ZIP；方式四 `bash install.sh --agent/--dir/--list`。移除 `npx skills` 与 `-g` 推荐；中英双 README 安装节同步。
+- 版本对齐：package.json / SKILL.md / CHANGELOG / 引擎 VERSION / 测试断言 / README 锚点 = 0.1.2。
+- 无功能变更（仅文档与版本同步）。
 ## v0.1.1 (2026-08-28)
 中英双语 README 对齐（老张拍板「英文门面 + 中文全档」）：

package/README.md CHANGED Viewed

@@ -1,163 +1,151 @@
-<p align="center"><b>Language</b>: English · <a href="./README.zh-CN.md">中文</a></p>
-<p align="center">
-  <img src="assets/banner.png" alt="yotta-guardian banner" width="100%" />
-</p>
-<h1 align="center">yotta-guardian · 元盾 (Yuandun)</h1>
-<p align="center">YottaMeta's tool-call interception guardrail: a <b>deterministic rule engine + pluggable intent verifier</b> that evaluates exec / write / edit / read / run / shell tool calls and returns <b>allow / deny + matched rules + audit logs</b>. Use it as a deterministic safety gate before an agent runs a high-risk command, writes a sensitive system path, or changes system configuration.</p>
-<p align="center">Activates when an agent is about to perform dangerous operations — recursive delete, disk formatting, privilege escalation, firewall changes, reverse shell, download-and-run, writes to core system files — <b>deterministic verdicts by rules, not prompt-engineering luck</b>.</p>
-<p align="center">Pure Python 3.8+ standard library, zero external dependencies; Windows + Linux + macOS; read-only evaluation by default, configurable allowances, full audit trail.</p>
-<p align="center">
-  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue" /></a>
-  <a href="https://agentskills.io/"><img alt="Standard: agentskills.io" src="https://img.shields.io/badge/standard-agentskills.io-orange" /></a>
-  <a href="https://www.npmjs.com/package/@yottameta/yotta-guardian"><img alt="npm package" src="https://img.shields.io/npm/v/@yottameta/yotta-guardian" /></a>
-  <a href="https://github.com/YottaMeta/yotta-guardian"><img alt="GitHub stars" src="https://img.shields.io/github/stars/YottaMeta/yotta-guardian" /></a>
-  <a href="https://github.com/YottaMeta/yotta-guardian/commits/main"><img alt="last commit" src="https://img.shields.io/github/last-commit/YottaMeta/yotta-guardian" /></a>
-  <a href="https://github.com/YottaMeta/yotta-guardian"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen" /></a>
-</p>
-## What it is
-When an AI agent acts autonomously, a single recursive delete, one disk write, or a download-and-run can cause irreversible damage. Yuandun packages these dangerous actions into a deterministic rule engine: every tool call (exec / write / edit / read / run / shell) is evaluated structurally — command text, argv-level verb and target analysis, sensitive paths, and written content — producing an allow / deny verdict with the matched rules and reasons, plus audit-log trails.
-It is not tied to any single platform: an agent-agnostic toolkit that works in any agent supporting Agent Skills. Read-only evaluation by default — it neither executes nor auto-approves dangerous actions; intent verification calls no model by default and can be plugged into any external verifier (e.g. an LLM gateway) through a JSON protocol.
-## Core value
-- **Deterministic rule engine** — text patterns (download-and-run / encoded execution / reverse shell) + argv-level verb/target analysis (rm / dd / mkfs / chmod / chown / privilege escalation / firewall / services / persistence) + sensitive paths + written content: four stacked layers of rules.
-- **Sensitive-path guard** — writes to /etc/passwd, /etc/sudoers, SSH authorized keys, /boot, /dev devices, Windows system directories and hosts, and registry startup entries are denied.
-- **Pluggable intent verification (no model required)** — zero-dependency by default; optional built-in local heuristics (--heuristic), or any external intent verifier via a stdin/stdout JSON protocol (--verifier / config file).
-- **Three policies** — default (deny high+), strict (deny medium+), loose (deny critical only), chosen per scenario.
-- **Audit trail** — JSONL audit log + audit query subcommand; every allow / deny is traceable.
-- **Machine readable** — --json outputs pure JSON (per-call verdicts, rules, exit codes); --batch pre-checks a list of calls, ideal as a pre-execution gate.
-## Why use it
-| Advantage | Description |
-|---|---|
-| **Zero dependency** | Python 3.8+ standard library; no daemon / database / external scanner; Windows + Linux + macOS |
-| **Deterministic** | Verdicts are reproducible and explainable, not model probability; intent verification is off by default and opt-in |
-| **Structural** | Evaluates commands, paths and content per tool type (exec / write / edit / read), not naive string matching |
-| **Configurable** | --allow / --allow-path / custom rule JSON (policy / deny / allow / verifier) |
-| **Traceable** | Every verdict lands in a JSONL audit log; audit subcommand filters by denied / tool / time |
-| **Ecosystem distribution** | GitHub + npm + ClawHub synced; install via npx / install.sh / manual copy |
-## Commands
-| Command | Description |
-|---|---|
-| check | Evaluate one or a batch of tool calls (--batch); text / JSON / Markdown reports |
-| audit | Query audit logs (--tail / --denied / --since / --tool / --json) |
-| rules | Print the built-in rule summary / validate a custom rules file |
-| version | Print the version |
-## Quick start
-Windows uses python, Linux/macOS uses python3.
-```bash
-# Check one exec call (0 = allowed)
-python3 scripts/yotta_guardian.py check exec --cmd "git status"
-# Check a dangerous command (denied by default, exit code 3)
-python3 scripts/yotta_guardian.py check exec --cmd "rm -rf /"
-# Check a write (writing /etc/passwd is denied)
-python3 scripts/yotta_guardian.py check write --path /etc/passwd --content "..."
-# Batch pre-check (the agent hands the pending call list to the guardrail before running)
-python3 scripts/yotta_guardian.py check --batch calls.json --json
-# Audit
-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
-```
-Exit codes (same semantics as the YuanAn / YuanShen family): **0** = allowed; **1** = allowed with warning (manual review recommended); **2** = denied (high); **3** = denied (critical); **4** = usage error / fatal exception.
-## Install
-Pick any one of the three methods; skill files are fetched from **npm** (GitHub is slower without a proxy; npm can use a domestic mirror).
-### Method 1: npm (recommended, one-liner)
-```bash
-# domestic mirror (optional): npm config set registry https://registry.npmmirror.com
-npx -y @yottameta/yotta-guardian -g
-npx -y @yottameta/yotta-guardian --dir <your-skills-dir>   # any agent: install to a specific directory
-```
-> Not in the preset list? Use --dir to point at the agent's skills directory, or manual copy (method 3). --list shows each agent's default directory. You can also npm pack @yottameta/yotta-guardian and unpack it to install via method 2 / 3.
-### Method 2: install.sh one-shot
-After obtaining the skill folder (npm pack unpack or git clone), enter the folder:
-```bash
-bash install.sh -g    # user level; bash install.sh --list shows all directories
-bash install.sh --agent codex   # specific agent (--list shows available ones)
-bash install.sh       # project level: auto-detect existing .claude/.cursor/.codex skills dirs
-bash install.sh --dir /path/to/skills
-```
-> Covers 17 agent families including Trae / Qwen / Comate / CodeBuddy / Kimi. Windows users: works with Git Bash; otherwise use method 3.
-### Method 3: manual copy
-Copy the whole yotta-guardian folder into the target agent's skills directory. Common locations (user level; Windows uses %USERPROFILE%, Linux/macOS uses ~):
-| Agent | User-level directory | Project-level directory |
-|---|---|---|
-| Codex | %USERPROFILE%\.codex\skills\yotta-guardian\ | .codex\skills\ |
-| Claude Code | %USERPROFILE%\.claude\skills\yotta-guardian\ | .claude\skills\ |
-| Cursor | %USERPROFILE%\.cursor\skills\yotta-guardian\ | .cursor\skills\ |
-| Windsurf | %USERPROFILE%\.codeium\windsurf\skills\yotta-guardian\ | .windsurf\skills\ |
-| opencode | %USERPROFILE%\.config\opencode\skills\yotta-guardian\ | .opencode\skills\ |
-| Gemini | %USERPROFILE%\.gemini\skills\yotta-guardian\ | .gemini\skills\ |
-| Goose | %USERPROFILE%\.config\goose\skills\yotta-guardian\ | .goose\skills\ |
-| Amp | %USERPROFILE%\.config\agents\skills\yotta-guardian\ | .agents\skills\ |
-| Kiro | %USERPROFILE%\.kiro\skills\yotta-guardian\ | .kiro\skills\ |
-| WorkBuddy | %USERPROFILE%\.workbuddy\skills\yotta-guardian\ | .workbuddy\skills\ |
-| Trae Code CLI | %USERPROFILE%\.traecli\skills\yotta-guardian\ | .traecli\skills\ |
-| Trae IDE (CN) | %USERPROFILE%\.trae-cn\skills\yotta-guardian\ | .trae\skills\ |
-| Qwen Code | %USERPROFILE%\.qwen\skills\yotta-guardian\ | .qwen\skills\ |
-| Comate | %USERPROFILE%\.comate\skills\yotta-guardian\ | .comate\skills\ |
-| CodeBuddy | %USERPROFILE%\.codebuddy\skills\yotta-guardian\ | .codebuddy\skills\ |
-| Kimi | %USERPROFILE%\.kimi\skills\yotta-guardian\ | .kimi\skills\ |
-| Generic AGENTS.md | %USERPROFILE%\.agents\skills\yotta-guardian\ | .agents\skills\ |
-> If Codex's CODEX_HOME is set, it overrides the default; the same applies to opencode's XDG_CONFIG_HOME. .agents\skills is not a universal directory — only OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot etc. read it; **Claude Code and Codex do not read it by default**. When unsure, use --dir or let the agent install it.
-## Usage examples (AI agent)
-1. Hook this repo's SKILL.md into any AI agent's skill/rule system (see install above).
-2. Before executing any high-risk tool call, run a check first:
-   ```bash
-   python3 scripts/yotta_guardian.py check exec --cmd "<pending command>" --json
-   ```
-   With exit code 2 / 3, do not execute — explain the matched rules to the user; only with explicit authorization use --allow / --allow-path / custom rules.
-3. For multiple calls, pre-check in batch:
-   ```bash
-   python3 scripts/yotta_guardian.py check --batch calls.json --json
-   ```
-4. Before writing sensitive paths / changing system config, check the target path and content with write / edit.
-5. High-risk operations land in the audit log; query them later with audit.
-## Boundaries (security red lines)
-- **Read-only evaluation by default** — does not execute, does not auto-approve, does not modify anything; it is a gate before execution, not a substitute for the user's decision.
-- **No hidden audit** — every verdict is recorded and traceable; rules are configurable but critical rules cannot be overridden.
-- **Authorization** — for explicitly authorized / own-asset / educational environments only; using it to bypass real-world authorization is the user's own responsibility.
-## Development & validation
-- Tests: python scripts/test_yotta_guardian.py (60 tests; Windows: python)
-- Base validation: python tools/validate-skill.py yotta-guardian (run at the repo root)
-- Rule details: references/rules.md; policies & exit codes: references/policies.md; intent-verifier protocol: references/intent-verifier.md
-Keep tests green and bump the version before releasing changes.
-## Changelog
-See [CHANGELOG.md](./CHANGELOG.md).
-## License
-[MIT](./LICENSE) © YottaMeta. "Yuandun" / "yotta-guardian" and the YottaMeta family names (yotta-* prefix) are YottaMeta brand identifiers; derived works must not reuse them, see [NOTICE](./NOTICE). The guardrail direction references open-source safe-guardian style skills; the implementation is YottaMeta's own new code.
+<p align="center"><b>Language</b>: English · <a href="./README.zh-CN.md">中文</a></p>
+<p align="center">
+  <img src="assets/banner.png" alt="yotta-guardian banner" width="100%" />
+</p>
+<h1 align="center">yotta-guardian · 元盾 (Yuandun)</h1>
+<p align="center">YottaMeta's tool-call interception guardrail: a <b>deterministic rule engine + pluggable intent verifier</b> that evaluates exec / write / edit / read / run / shell tool calls and returns <b>allow / deny + matched rules + audit logs</b>. Use it as a deterministic safety gate before an agent runs a high-risk command, writes a sensitive system path, or changes system configuration.</p>
+<p align="center">Activates when an agent is about to perform dangerous operations — recursive delete, disk formatting, privilege escalation, firewall changes, reverse shell, download-and-run, writes to core system files — <b>deterministic verdicts by rules, not prompt-engineering luck</b>.</p>
+<p align="center">Pure Python 3.8+ standard library, zero external dependencies; Windows + Linux + macOS; read-only evaluation by default, configurable allowances, full audit trail.</p>
+<p align="center">
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue" /></a>
+  <a href="https://agentskills.io/"><img alt="Standard: agentskills.io" src="https://img.shields.io/badge/standard-agentskills.io-orange" /></a>
+  <a href="https://www.npmjs.com/package/@yottameta/yotta-guardian"><img alt="npm package" src="https://img.shields.io/npm/v/@yottameta/yotta-guardian" /></a>
+  <a href="https://github.com/YottaMeta/yotta-guardian"><img alt="GitHub stars" src="https://img.shields.io/github/stars/YottaMeta/yotta-guardian" /></a>
+  <a href="https://github.com/YottaMeta/yotta-guardian/commits/main"><img alt="last commit" src="https://img.shields.io/github/last-commit/YottaMeta/yotta-guardian" /></a>
+  <a href="https://github.com/YottaMeta/yotta-guardian"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen" /></a>
+</p>
+## What it is
+When an AI agent acts autonomously, a single recursive delete, one disk write, or a download-and-run can cause irreversible damage. Yuandun packages these dangerous actions into a deterministic rule engine: every tool call (exec / write / edit / read / run / shell) is evaluated structurally — command text, argv-level verb and target analysis, sensitive paths, and written content — producing an allow / deny verdict with the matched rules and reasons, plus audit-log trails.
+It is not tied to any single platform: an agent-agnostic toolkit that works in any agent supporting Agent Skills. Read-only evaluation by default — it neither executes nor auto-approves dangerous actions; intent verification calls no model by default and can be plugged into any external verifier (e.g. an LLM gateway) through a JSON protocol.
+## Core value
+- **Deterministic rule engine** — text patterns (download-and-run / encoded execution / reverse shell) + argv-level verb/target analysis (rm / dd / mkfs / chmod / chown / privilege escalation / firewall / services / persistence) + sensitive paths + written content: four stacked layers of rules.
+- **Sensitive-path guard** — writes to /etc/passwd, /etc/sudoers, SSH authorized keys, /boot, /dev devices, Windows system directories and hosts, and registry startup entries are denied.
+- **Pluggable intent verification (no model required)** — zero-dependency by default; optional built-in local heuristics (--heuristic), or any external intent verifier via a stdin/stdout JSON protocol (--verifier / config file).
+- **Three policies** — default (deny high+), strict (deny medium+), loose (deny critical only), chosen per scenario.
+- **Audit trail** — JSONL audit log + audit query subcommand; every allow / deny is traceable.
+- **Machine readable** — --json outputs pure JSON (per-call verdicts, rules, exit codes); --batch pre-checks a list of calls, ideal as a pre-execution gate.
+## Why use it
+| Advantage | Description |
+|---|---|
+| **Zero dependency** | Python 3.8+ standard library; no daemon / database / external scanner; Windows + Linux + macOS |
+| **Deterministic** | Verdicts are reproducible and explainable, not model probability; intent verification is off by default and opt-in |
+| **Structural** | Evaluates commands, paths and content per tool type (exec / write / edit / read), not naive string matching |
+| **Configurable** | --allow / --allow-path / custom rule JSON (policy / deny / allow / verifier) |
+| **Traceable** | Every verdict lands in a JSONL audit log; audit subcommand filters by denied / tool / time |
+| **Ecosystem distribution** | GitHub + npm + ClawHub synced; four install methods (npx / git clone / Download ZIP / install.sh) |
+## Commands
+| Command | Description |
+|---|---|
+| check | Evaluate one or a batch of tool calls (--batch); text / JSON / Markdown reports |
+| audit | Query audit logs (--tail / --denied / --since / --tool / --json) |
+| rules | Print the built-in rule summary / validate a custom rules file |
+| version | Print the version |
+## Quick start
+Windows uses python, Linux/macOS uses python3.
+```bash
+# Check one exec call (0 = allowed)
+python3 scripts/yotta_guardian.py check exec --cmd "git status"
+# Check a dangerous command (denied by default, exit code 3)
+python3 scripts/yotta_guardian.py check exec --cmd "rm -rf /"
+# Check a write (writing /etc/passwd is denied)
+python3 scripts/yotta_guardian.py check write --path /etc/passwd --content "..."
+# Batch pre-check (the agent hands the pending call list to the guardrail before running)
+python3 scripts/yotta_guardian.py check --batch calls.json --json
+# Audit
+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
+```
+Exit codes (same semantics as the YuanAn / YuanShen family): **0** = allowed; **1** = allowed with warning (manual review recommended); **2** = denied (high); **3** = denied (critical); **4** = usage error / fatal exception.
+## Install
+Pick any of the four methods below; the order is the recommended priority. Skill files always come from **npm** (GitHub can be slow without a proxy; npm supports mirrors).
+### Method 1: npm one-liner (recommended)
+```text
+# Optional China mirror: npm config set registry https://registry.npmmirror.com
+npx -y @yottameta/yotta-guardian --agent <agent-name>      # install to the agent's default user-level skills dir
+npx -y @yottameta/yotta-guardian --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.
+- `--dir <path>` installs to the given directory; for agents not in the preset list, point `--dir` at their skills directory.
+- If the mirror has not synced the new package (404): add `--registry=https://registry.npmjs.org/` (a proxy may be needed in China), or wait for the mirror cache.
+### Method 2: git clone (developers / git available)
+```text
+git clone https://github.com/YottaMeta/yotta-guardian.git <your-skills-dir>/yotta-guardian
+```
+### Method 3: GitHub Download ZIP (manual / no git)
+On the GitHub repository `YottaMeta/yotta-guardian`, click **Code → Download ZIP**, unzip it and put the `yotta-guardian` folder into the agent's skills directory.
+### Method 4: install.sh (multi-agent one-liner script)
+```text
+bash install.sh --agent <name>   # install to the agent's default user-level directory
+bash install.sh --dir <path>     # install to the given directory
+bash install.sh --list           # list agents -> default directories
+```
+> Method 1 uses the npm registry (npmmirror / npmjs) and does not depend on GitHub; Methods 2/3 use GitHub and may fail without a proxy in China.
+## Usage examples (AI agent)
+1. Hook this repo's SKILL.md into any AI agent's skill/rule system (see install above).
+2. Before executing any high-risk tool call, run a check first:
+   ```bash
+   python3 scripts/yotta_guardian.py check exec --cmd "<pending command>" --json
+   ```
+   With exit code 2 / 3, do not execute — explain the matched rules to the user; only with explicit authorization use --allow / --allow-path / custom rules.
+3. For multiple calls, pre-check in batch:
+   ```bash
+   python3 scripts/yotta_guardian.py check --batch calls.json --json
+   ```
+4. Before writing sensitive paths / changing system config, check the target path and content with write / edit.
+5. High-risk operations land in the audit log; query them later with audit.
+## Boundaries (security red lines)
+- **Read-only evaluation by default** — does not execute, does not auto-approve, does not modify anything; it is a gate before execution, not a substitute for the user's decision.
+- **No hidden audit** — every verdict is recorded and traceable; rules are configurable but critical rules cannot be overridden.
+- **Authorization** — for explicitly authorized / own-asset / educational environments only; using it to bypass real-world authorization is the user's own responsibility.
+## Development & validation
+- Tests: python scripts/test_yotta_guardian.py (60 tests; Windows: python)
+- Base validation: python tools/validate-skill.py yotta-guardian (run at the repo root)
+- Rule details: references/rules.md; policies & exit codes: references/policies.md; intent-verifier protocol: references/intent-verifier.md
+Keep tests green and bump the version before releasing changes.
+## Changelog
+See [CHANGELOG.md](./CHANGELOG.md).
+## License
+[MIT](./LICENSE) © YottaMeta. "Yuandun" / "yotta-guardian" and the YottaMeta family names (yotta-* prefix) are YottaMeta brand identifiers; derived works must not reuse them, see [NOTICE](./NOTICE). The guardrail direction references open-source safe-guardian style skills; the implementation is YottaMeta's own new code.

package/README.zh-CN.md CHANGED Viewed

@@ -44,7 +44,7 @@ AI 代理在自主执行时，一条递归删除、一次磁盘写入、一段
 | **结构化** | 按工具类型（exec / write / edit / read）分别评估命令、路径与内容，不是简单字符串匹配 |
 | **可配置** | --allow / --allow-path / 自定义规则 JSON（policy / deny / allow / verifier） |
 | **可追溯** | 每次判定落 JSONL 审计日志，audit 子命令可按拒绝 / 工具 / 时间过滤 |
-| **生态分发** | GitHub + npm + ClawHub 三源同步发布；npx / install.sh / 手动复制三种安装方式 |
+| **生态分发** | GitHub + npm + ClawHub 三源同步发布；npx / git clone / Download ZIP / install.sh 四种安装方式 |
 ## 功能体系
@@ -59,7 +59,7 @@ AI 代理在自主执行时，一条递归删除、一次磁盘写入、一段
 Windows 用 python，Linux/macOS 用 python3。
-`````bash
+```bash
 # 检查一条 exec（0 = 允许）
 python3 scripts/yotta_guardian.py check exec --cmd "git status"
@@ -75,69 +75,57 @@ 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
-`````
+```
 退出码语义（与元安 / 元审家族一致）：0 = 允许；1 = 允许但带警告（建议人工复核）；2 = 拒绝（high）；3 = 拒绝（critical）；4 = 用法错误 / 致命异常。
 ## 安装
-三种方式任选其一，技能文件统一从 **npm** 获取（GitHub 无代理时较慢，npm 可配国内镜像加速）。
-### 方式一：npm（推荐，一行安装）
-`````bash
-# 国内加速（可选）：npm config set registry https://registry.npmmirror.com
-npx -y @yottameta/yotta-guardian -g
-npx -y @yottameta/yotta-guardian --dir <你的技能目录>   # 任意智能体：指定目录安装
-`````
-> 智能体不在预置列表里？用 --dir 指定它的 skills 目录，或手动复制（方式三）。--list 可查看各智能体对应的默认目录。想手动拿文件也可 npm pack @yottameta/yotta-guardian 解包后按方式二/三安装。
-### 方式二：install.sh 一键安装
-获取技能文件夹后（npm pack 解包或 git clone），进入技能文件夹：
-`````bash
-bash install.sh -g    # 用户级；bash install.sh --list 查看全部目录
-bash install.sh --agent codex   # 指定智能体（--list 可查看可用项）
-bash install.sh       # 项目级：自动检测已存在的 .claude/.cursor/.codex 等 skills 目录
-bash install.sh --dir /path/to/skills
-`````
-> 覆盖 17 类智能体，含国内 Trae / Qwen / Comate / CodeBuddy / Kimi。Windows 用户：装有 Git Bash 即可用；否则用方式三手动复制。
-### 方式三：手动复制
-把整个 yotta-guardian 文件夹复制到目标智能体的 skills 目录。常见位置（用户级；Windows 用 %USERPROFILE%，Linux/macOS 用 ~）：
-| 智能体 | 用户级目录 | 项目级目录 |
-|---|---|---|
-| Codex | %USERPROFILE%\.codex\skills\yotta-guardian\ | .codex\skills\ |
-| Claude Code | %USERPROFILE%\.claude\skills\yotta-guardian\ | .claude\skills\ |
-| Cursor | %USERPROFILE%\.cursor\skills\yotta-guardian\ | .cursor\skills\ |
-| Windsurf | %USERPROFILE%\.codeium\windsurf\skills\yotta-guardian\ | .windsurf\skills\ |
-| opencode | %USERPROFILE%\.config\opencode\skills\yotta-guardian\ | .opencode\skills\ |
-| Gemini | %USERPROFILE%\.gemini\skills\yotta-guardian\ | .gemini\skills\ |
-| Goose | %USERPROFILE%\.config\goose\skills\yotta-guardian\ | .goose\skills\ |
-| Amp | %USERPROFILE%\.config\agents\skills\yotta-guardian\ | .agents\skills\ |
-| Kiro | %USERPROFILE%\.kiro\skills\yotta-guardian\ | .kiro\skills\ |
-| WorkBuddy | %USERPROFILE%\.workbuddy\skills\yotta-guardian\ | .workbuddy\skills\ |
-| Trae Code CLI | %USERPROFILE%\.traecli\skills\yotta-guardian\ | .traecli\skills\ |
-| Trae IDE（国内） | %USERPROFILE%\.trae-cn\skills\yotta-guardian\ | .trae\skills\ |
-| Qwen Code | %USERPROFILE%\.qwen\skills\yotta-guardian\ | .qwen\skills\ |
-| Comate | %USERPROFILE%\.comate\skills\yotta-guardian\ | .comate\skills\ |
-| CodeBuddy | %USERPROFILE%\.codebuddy\skills\yotta-guardian\ | .codebuddy\skills\ |
-| Kimi | %USERPROFILE%\.kimi\skills\yotta-guardian\ | .kimi\skills\ |
-| 通用 AGENTS.md | %USERPROFILE%\.agents\skills\yotta-guardian\ | .agents\skills\ |
-> Codex 默认目录若设置了环境变量 CODEX_HOME，以该变量为准；opencode 若设置 XDG_CONFIG_HOME 同理。.agents\skills 并非通用目录，仅 OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot 等会读取，Claude Code 与 Codex 默认不读。不确定时用 --dir 指定，或让该智能体自行安装。
+以下四种方式任选，顺序即推荐优先级；技能文件一律从 **npm** 获取（GitHub 无代理较慢，npm 支持镜像）。
+### 方式一：npm 一行装（推荐）
+```text
+# 可选国内加速：npm config set registry https://registry.npmmirror.com
+npx -y @yottameta/yotta-guardian --agent <智能体名称>      # 装到指定智能体默认用户级技能目录
+npx -y @yottameta/yotta-guardian --dir <智能体的技能目录>  # 指到技能目录本身（如 ~/.codex/skills）
+```
+- `--agent <name>` 自动装到该智能体默认用户级目录；`--list` 可查看各智能体默认目录。
+- `--dir <路径>` 装到指定的技能目录；未收录的智能体用 `--dir` 指到它的技能目录。
+- npmmirror 未同步新包（404）：加 `--registry=https://registry.npmjs.org/`（国内需代理），或稍等镜像缓存。
+### 方式二：git clone（开发者 / 有 git 环境）
+```text
+git clone https://github.com/YottaMeta/yotta-guardian.git <智能体的技能目录>/yotta-guardian
+```
+### 方式三：GitHub 下载压缩包（手动 / 无 git 环境）
+在 GitHub 仓库 `YottaMeta/yotta-guardian` 点 **Code → Download ZIP**，解压后把 `yotta-guardian` 文件夹放进智能体技能目录。
+### 方式四：install.sh（多智能体一键脚本）
+```text
+bash install.sh --agent <name>   # 装到指定智能体默认用户级目录
+bash install.sh --dir <path>     # 装到指定目录
+bash install.sh --list           # 列出智能体 -> 默认目录
+```
+> 方式一走 npm 源（npmmirror / npmjs），不依赖 GitHub；方式二 / 三走 GitHub，国内无代理可能失败。
 ## 使用示例（AI 智能体）
 1. 将本仓库的 SKILL.md 接入任意 AI 智能体的技能/规则系统（见上方安装）。
 2. 在执行任何高风险工具调用前，先跑一次 check：
-   `````bash
+   ```bash
    python3 scripts/yotta_guardian.py check exec --cmd "<待执行命令>" --json
-   `````
+   ```
    退出码 2 / 3 时不要执行，向用户说明命中规则；确有授权再用 --allow / --allow-path / 自定义规则放行。
 3. 一次要执行多条时，用 --batch 批量预检：
-   `````bash
+   ```bash
    python3 scripts/yotta_guardian.py check --batch calls.json --json
-   `````
+   ```
 4. 写敏感路径 / 修改系统配置前，用 write / edit 检查目标路径与内容。
 5. 高风险操作落审计日志，事后用 audit 查询。

package/SKILL.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 name: yotta-guardian
-version: 0.1.1
+version: 0.1.2
 description: 元盾 —— 跨智能体的危险调用拦截护栏：确定性规则引擎 + 可插拔意图验证（不绑模型），拦截危险 exec / write / edit / read / run / shell 工具调用，提供审计日志。触发：代理要执行高风险命令（递归删除、磁盘格式化、提权、防火墙改动、反向 shell、下载即执行等）、要写入系统敏感路径或修改系统配置、要在执行危险操作前做安全检查、或用户说 护栏/拦截/危险操作/安全检查 等。边界：默认只读评估，不自动执行也不放行危险操作；不替代用户决策；不隐藏审计记录；规则可配置。
 license: MIT
 ---

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-guardian",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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/scripts/yotta_guardian.py CHANGED Viewed

@@ -51,7 +51,7 @@ _HERE = Path(__file__).resolve().parent
 sys.path.insert(0, str(_HERE))
 import guardian_rules as GR  # noqa: E402
-VERSION = "0.1.1"
+VERSION = "0.1.2"
 TOOL_NAME = "yotta-guardian"
 TOOL_CN = "元盾"