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

@yottameta/yotta-guardian 0.1.0 → 0.1.1

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 (9) hide show

package/CHANGELOG.md +11 -0
package/README.md +163 -154
package/README.zh-CN.md +156 -0
package/SKILL.md +1 -1
package/package.json +6 -4
package/scripts/yotta_guardian.py +1 -1
package/scripts/__pycache__/guardian_rules.cpython-38.pyc +0 -0
package/scripts/__pycache__/test_yotta_guardian.cpython-38.pyc +0 -0
package/scripts/__pycache__/yotta_guardian.cpython-38.pyc +0 -0

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,16 @@
 # 更新日志
+## v0.1.1 (2026-08-28)
+中英双语 README 对齐（老张拍板「英文门面 + 中文全档」）：
+- **README.md 改为英文**：作为 GitHub / npm / ClawHub 首页的英文门面（翻译 + 精简，覆盖定位 / 核心价值 / 命令 / 快速使用 / 安装 / 使用示例 / 边界 / 开发校验全流程）。
+- **新增 README.zh-CN.md**：原中文完整主文档整体平移，顶部加语言切换链接。
+- **修复代码围栏**：README 中 `_BT_`bash / `_BT_` 占位符全部改为标准 ```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 触发描述保持中文。
 ## v0.1.0 (2026-08-26)
 YottaMeta 自有实现首版（护栏/拦截方向参考开源社区 safe-guardian 类技能思路，已完全重写，零依赖、无上游代码）：

package/README.md CHANGED Viewed

@@ -1,154 +1,163 @@
-<p align="center">
-  <img src="assets/banner.png" alt="yotta-guardian banner" width="100%" />
-</p>
-<h1 align="center">yotta-guardian · 元盾</h1>
-<p align="center">YottaMeta 自有的工具调用拦截护栏：<b>确定性规则引擎 + 可插拔意图验证</b>，对 exec / write / edit / read / run / shell 工具调用做安全评估，输出 allow / deny + 命中规则 + 审计日志。适用于代理要执行高风险命令、写入系统敏感路径、或修改系统配置之前的确定性安全检查。</p>
-<p align="center">检测到递归删除、磁盘格式化、提权、防火墙改动、反向 shell、下载即执行、写入系统核心文件等危险操作意图时自动激活——<b>不靠提示词兜底，按规则确定性判定</b>。</p>
-<p align="center">纯 Python 3.8+ 标准库实现，零外部依赖；Windows + Linux + macOS 通用；默认只读评估、可配置放行、审计留痕。</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>
-## 这是什么
-AI 代理在自主执行时，一条递归删除、一次磁盘写入、一段下载即执行，就可能造成不可逆损失。元盾把这些危险动作做成确定性规则引擎：对每一次工具调用（exec / write / edit / read / run / shell）做结构化评估——命令文本、argv 级动词与目标分析、敏感路径、写入内容——给出 allow / deny 判定、命中规则与原因，并支持审计日志留痕。
-它不是某个平台的专属功能，而是一份与智能体无关的工具包：装进任何支持 Agent Skills 的智能体即可按需调用。默认只读评估，不自动执行也不放行危险操作；意图验证默认不调用任何模型，可通过协议外接任意验证器（如 LLM 网关）。
-## 核心价值
-- **确定性规则引擎**：文本模式（下载即执行 / 编码执行 / 反向 shell 等）+ argv 级动词/目标分析（rm / dd / mkfs / chmod / chown / 提权 / 防火墙 / 服务 / 持久化等）+ 敏感路径 + 写入内容，四层规则叠加判定。
-- **敏感路径守卫**：/etc/passwd、/etc/sudoers、SSH 授权文件、/boot、/dev 设备、Windows 系统目录与 hosts、注册表启动项等写入即拒。
-- **可插拔意图验证（不绑模型）**：默认零依赖；可启用内置本地启发式（--heuristic），也可通过 stdin/stdout JSON 协议外接任意意图验证器（--verifier / 配置文件）。
-- **三档策略**：default（拒绝 high+）/ strict（拒绝 medium+）/ loose（仅拒绝 critical），按场景取舍。
-- **审计留痕**：JSONL 审计日志 + audit 查询子命令，拒绝/放行全程可追溯。
-- **机器可读**：--json 输出纯净 JSON（含逐条判定、规则、退出码），--batch 批量预检，适合智能体在执行前 gate。
-## 核心优势
-| 优势 | 说明 |
-|---|---|
-| **零依赖** | Python 3.8+ 标准库，无 daemon / 无数据库 / 无外部扫描器；Windows + Linux + macOS 通用 |
-| **确定性** | 规则判定可复现、可解释，不依赖模型概率；意图验证默认关闭，需显式启用 |
-| **结构化** | 按工具类型（exec / write / edit / read）分别评估命令、路径与内容，不是简单字符串匹配 |
-| **可配置** | --allow / --allow-path / 自定义规则 JSON（policy / deny / allow / verifier） |
-| **可追溯** | 每次判定落 JSONL 审计日志，audit 子命令可按拒绝 / 工具 / 时间过滤 |
-| **生态分发** | GitHub + npm + ClawHub 三源同步发布；npx / install.sh / 手动复制三种安装方式 |
-## 功能体系
-| 能力 | 说明 |
-|---|---|
-| check | 评估一条或一批工具调用（--batch），文本 / JSON / Markdown 报告三种输出 |
-| audit | 查询审计日志（--tail / --denied / --since / --tool / --json） |
-| rules | 打印内置规则摘要 / 校验自定义规则文件 |
-| version | 打印版本 |
-## 快速使用
-Windows 用 python，Linux/macOS 用 python3。
-`_BT_`bash
-# 检查一条 exec（0 = 允许）
-python3 scripts/yotta_guardian.py check exec --cmd "git status"
-# 检查危险命令（默认拒绝，退出码 3）
-python3 scripts/yotta_guardian.py check exec --cmd "rm -rf /"
-# 检查写操作（写入 /etc/passwd 被拒）
-python3 scripts/yotta_guardian.py check write --path /etc/passwd --content "..."
-# 批量预检（agent 在执行前把待执行调用列表交给护栏）
-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_`
-退出码语义（与元安 / 元审家族一致）：0 = 允许；1 = 允许但带警告（建议人工复核）；2 = 拒绝（high）；3 = 拒绝（critical）；4 = 用法错误 / 致命异常。
-## 安装
-三种方式任选其一，技能文件统一从 **npm** 获取（GitHub 无代理时较慢，npm 可配国内镜像加速）。
-### 方式一：npm（推荐，一行安装）
-`_BT_`bash
-# 国内加速（可选）：npm config set registry https://registry.npmmirror.com
-npx -y @yottameta/yotta-guardian -g
-npx -y @yottameta/yotta-guardian --dir <你的技能目录>   # 任意智能体：指定目录安装
-`_BT_`
-> 智能体不在预置列表里？用 --dir 指定它的 skills 目录，或手动复制（方式三）。--list 可查看各智能体对应的默认目录。想手动拿文件也可 npm pack @yottameta/yotta-guardian 解包后按方式二/三安装。
-### 方式二：install.sh 一键安装
-获取技能文件夹后（npm pack 解包或 git clone），进入技能文件夹：
-`_BT_`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
-`_BT_`
-> 覆盖 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 指定，或让该智能体自行安装。
-## 使用示例（AI 智能体）
-1. 将本仓库的 SKILL.md 接入任意 AI 智能体的技能/规则系统（见上方安装）。
-2. 在执行任何高风险工具调用前，先跑一次 check：
-   `_BT_`bash
-   python3 scripts/yotta_guardian.py check exec --cmd "<待执行命令>" --json
-   `_BT_`
-   退出码 2 / 3 时不要执行，向用户说明命中规则；确有授权再用 --allow / --allow-path / 自定义规则放行。
-3. 一次要执行多条时，用 --batch 批量预检：
-   `_BT_`bash
-   python3 scripts/yotta_guardian.py check --batch calls.json --json
-   `_BT_`
-4. 写敏感路径 / 修改系统配置前，用 write / edit 检查目标路径与内容。
-5. 高风险操作落审计日志，事后用 audit 查询。
-## 开发与校验
-- 测试：python scripts/test_yotta_guardian.py（60 项）
-- 基础校验：python tools/validate-skill.py yotta-guardian（在仓库根目录运行）
-- 规则说明：references/rules.md；策略与退出码：references/policies.md；意图验证器协议：references/intent-verifier.md
-## 许可证
-MIT © YottaMeta —— 详见 [LICENSE](./LICENSE)。
-## 致谢
-护栏/拦截方向参考开源社区 safe-guardian 类技能思路，实现为 YottaMeta 全新自有代码（详见 [NOTICE](./NOTICE)）。
+<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.

package/README.zh-CN.md ADDED Viewed

@@ -0,0 +1,156 @@
+<p align="center"><b>Language</b>: <a href="./README.md">English</a> · 中文</p>
+<p align="center">
+  <img src="assets/banner.png" alt="yotta-guardian banner" width="100%" />
+</p>
+<h1 align="center">yotta-guardian · 元盾</h1>
+<p align="center">YottaMeta 自有的工具调用拦截护栏：<b>确定性规则引擎 + 可插拔意图验证</b>，对 exec / write / edit / read / run / shell 工具调用做安全评估，输出 allow / deny + 命中规则 + 审计日志。适用于代理要执行高风险命令、写入系统敏感路径、或修改系统配置之前的确定性安全检查。</p>
+<p align="center">检测到递归删除、磁盘格式化、提权、防火墙改动、反向 shell、下载即执行、写入系统核心文件等危险操作意图时自动激活——<b>不靠提示词兜底，按规则确定性判定</b>。</p>
+<p align="center">纯 Python 3.8+ 标准库实现，零外部依赖；Windows + Linux + macOS 通用；默认只读评估、可配置放行、审计留痕。</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>
+## 这是什么
+AI 代理在自主执行时，一条递归删除、一次磁盘写入、一段下载即执行，就可能造成不可逆损失。元盾把这些危险动作做成确定性规则引擎：对每一次工具调用（exec / write / edit / read / run / shell）做结构化评估——命令文本、argv 级动词与目标分析、敏感路径、写入内容——给出 allow / deny 判定、命中规则与原因，并支持审计日志留痕。
+它不是某个平台的专属功能，而是一份与智能体无关的工具包：装进任何支持 Agent Skills 的智能体即可按需调用。默认只读评估，不自动执行也不放行危险操作；意图验证默认不调用任何模型，可通过协议外接任意验证器（如 LLM 网关）。
+## 核心价值
+- **确定性规则引擎**：文本模式（下载即执行 / 编码执行 / 反向 shell 等）+ argv 级动词/目标分析（rm / dd / mkfs / chmod / chown / 提权 / 防火墙 / 服务 / 持久化等）+ 敏感路径 + 写入内容，四层规则叠加判定。
+- **敏感路径守卫**：/etc/passwd、/etc/sudoers、SSH 授权文件、/boot、/dev 设备、Windows 系统目录与 hosts、注册表启动项等写入即拒。
+- **可插拔意图验证（不绑模型）**：默认零依赖；可启用内置本地启发式（--heuristic），也可通过 stdin/stdout JSON 协议外接任意意图验证器（--verifier / 配置文件）。
+- **三档策略**：default（拒绝 high+）/ strict（拒绝 medium+）/ loose（仅拒绝 critical），按场景取舍。
+- **审计留痕**：JSONL 审计日志 + audit 查询子命令，拒绝/放行全程可追溯。
+- **机器可读**：--json 输出纯净 JSON（含逐条判定、规则、退出码），--batch 批量预检，适合智能体在执行前 gate。
+## 核心优势
+| 优势 | 说明 |
+|---|---|
+| **零依赖** | Python 3.8+ 标准库，无 daemon / 无数据库 / 无外部扫描器；Windows + Linux + macOS 通用 |
+| **确定性** | 规则判定可复现、可解释，不依赖模型概率；意图验证默认关闭，需显式启用 |
+| **结构化** | 按工具类型（exec / write / edit / read）分别评估命令、路径与内容，不是简单字符串匹配 |
+| **可配置** | --allow / --allow-path / 自定义规则 JSON（policy / deny / allow / verifier） |
+| **可追溯** | 每次判定落 JSONL 审计日志，audit 子命令可按拒绝 / 工具 / 时间过滤 |
+| **生态分发** | GitHub + npm + ClawHub 三源同步发布；npx / install.sh / 手动复制三种安装方式 |
+## 功能体系
+| 能力 | 说明 |
+|---|---|
+| check | 评估一条或一批工具调用（--batch），文本 / JSON / Markdown 报告三种输出 |
+| audit | 查询审计日志（--tail / --denied / --since / --tool / --json） |
+| rules | 打印内置规则摘要 / 校验自定义规则文件 |
+| version | 打印版本 |
+## 快速使用
+Windows 用 python，Linux/macOS 用 python3。
+`````bash
+# 检查一条 exec（0 = 允许）
+python3 scripts/yotta_guardian.py check exec --cmd "git status"
+# 检查危险命令（默认拒绝，退出码 3）
+python3 scripts/yotta_guardian.py check exec --cmd "rm -rf /"
+# 检查写操作（写入 /etc/passwd 被拒）
+python3 scripts/yotta_guardian.py check write --path /etc/passwd --content "..."
+# 批量预检（agent 在执行前把待执行调用列表交给护栏）
+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 指定，或让该智能体自行安装。
+## 使用示例（AI 智能体）
+1. 将本仓库的 SKILL.md 接入任意 AI 智能体的技能/规则系统（见上方安装）。
+2. 在执行任何高风险工具调用前，先跑一次 check：
+   `````bash
+   python3 scripts/yotta_guardian.py check exec --cmd "<待执行命令>" --json
+   `````
+   退出码 2 / 3 时不要执行，向用户说明命中规则；确有授权再用 --allow / --allow-path / 自定义规则放行。
+3. 一次要执行多条时，用 --batch 批量预检：
+   `````bash
+   python3 scripts/yotta_guardian.py check --batch calls.json --json
+   `````
+4. 写敏感路径 / 修改系统配置前，用 write / edit 检查目标路径与内容。
+5. 高风险操作落审计日志，事后用 audit 查询。
+## 开发与校验
+- 测试：python scripts/test_yotta_guardian.py（60 项）
+- 基础校验：python tools/validate-skill.py yotta-guardian（在仓库根目录运行）
+- 规则说明：references/rules.md；策略与退出码：references/policies.md；意图验证器协议：references/intent-verifier.md
+## 许可证
+MIT © YottaMeta —— 详见 [LICENSE](./LICENSE)。
+## 致谢
+护栏/拦截方向参考开源社区 safe-guardian 类技能思路，实现为 YottaMeta 全新自有代码（详见 [NOTICE](./NOTICE)）。

package/SKILL.md CHANGED Viewed

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

package/package.json CHANGED Viewed

@@ -1,11 +1,12 @@
 {
   "name": "@yottameta/yotta-guardian",
-  "version": "0.1.0",
-  "description": "元盾 —— 跨智能体的危险调用拦截护栏：确定性规则引擎 + 可插拔意图验证（不绑模型），拦截危险 exec/write/edit 等工具调用，提供审计日志。触发：代理要执行高风险命令、写敏感路径、改系统配置时。边界：默认只读检查，不自动放行危险操作；规则可配置。",
+  "version": "0.1.1",
+  "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": [
     "agent-skills",
-    "yotta-guardian"
+    "yotta-guardian",
+    "security"
   ],
   "files": [
     "SKILL.md",
@@ -17,7 +18,8 @@
     "assets",
     "bin",
     "NOTICE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "README.zh-CN.md"
   ],
   "repository": {
     "type": "git",

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.0"
+VERSION = "0.1.1"
 TOOL_NAME = "yotta-guardian"
 TOOL_CN = "元盾"

package/scripts/__pycache__/guardian_rules.cpython-38.pyc DELETED Viewed

Binary file

package/scripts/__pycache__/test_yotta_guardian.cpython-38.pyc DELETED Viewed

Binary file

package/scripts/__pycache__/yotta_guardian.cpython-38.pyc DELETED Viewed

Binary file