@yottameta/yotta-vetter 0.1.2 → 0.1.4
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.
- package/CHANGELOG.md +18 -0
- package/README.md +105 -90
- package/README.zh-CN.md +156 -0
- package/SKILL.md +1 -1
- package/package.json +4 -3
- package/scripts/__pycache__/vetter_rules.cpython-38.pyc +0 -0
- package/scripts/yotta_vetter.py +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,23 @@
|
|
|
1
1
|
# 更新日志
|
|
2
2
|
|
|
3
|
+
## v0.1.4 (2026-08-29)
|
|
4
|
+
|
|
5
|
+
维护性修复（签名数据豁免）：
|
|
6
|
+
|
|
7
|
+
- 规则表豁免列表加入 `verify_rules.py`（yotta-verify 规则表）：元审检查 yotta-verify 时
|
|
8
|
+
规则表自身字面量不再误报（keychain / id_rsa / DPAPI 等检测模式属签名数据）。
|
|
9
|
+
|
|
10
|
+
## v0.1.3 (2026-08-28)
|
|
11
|
+
|
|
12
|
+
中英双语 README 对齐 + 版本统一（老张拍板「英文门面 + 中文全档」）：
|
|
13
|
+
|
|
14
|
+
- **README.md 改为英文**：作为 GitHub / npm / ClawHub 首页的英文门面（翻译 + 精简，覆盖定位 / 核心价值 / 四阶段协议 / 结论判定 / 使用示例 / 安装 / 升级卸载 / 常见问题 / 相关技能 / 边界 / 开发校验全流程）。
|
|
15
|
+
- **新增 README.zh-CN.md**：原中文完整主文档整体平移，顶部加语言切换链接。
|
|
16
|
+
- **移除 npx --agent codex 安装行**：README 安装方式一不再出现 `npx -y @yottameta/... --agent <name>`（固定智能体名，违反安装规范；npx 用 -g 或 --dir，--agent 仅 install.sh 用）。
|
|
17
|
+
- **版本统一 0.1.3**：此前 package.json=0.1.2、CHANGELOG 顶部=0.1.1、引擎 VERSION=0.1.0 不一致；本版统一为 0.1.3（package.json / SKILL frontmatter / 引擎 VERSION / CHANGELOG / 测试断言全对齐）。
|
|
18
|
+
- **package.json**：description 改英文；files 加 README.zh-CN.md。
|
|
19
|
+
- 边界（B 方案）：references / CHANGELOG / 测试注释不翻译；SKILL 触发描述保持中文。
|
|
20
|
+
|
|
3
21
|
## v0.1.1 (2026-08-26)
|
|
4
22
|
|
|
5
23
|
README 按标准补全：新增「这是什么 / 核心价值 / 核心优势 / 四阶段协议 / 结论判定 / 常见问题 / 相关技能 / 升级卸载」等章节，与 YottaMeta 技能矩阵 README 标准对齐；无功能变更。
|
package/README.md
CHANGED
|
@@ -1,12 +1,14 @@
|
|
|
1
|
+
<p align="center"><b>Language</b>: English · <a href="./README.zh-CN.md">中文</a></p>
|
|
2
|
+
|
|
1
3
|
<p align="center">
|
|
2
4
|
<img src="assets/banner.png" alt="yotta-vetter banner" width="100%" />
|
|
3
5
|
</p>
|
|
4
6
|
|
|
5
|
-
<h1 align="center">yotta-vetter ·
|
|
7
|
+
<h1 align="center">yotta-vetter · 元审 (Yuanshen)</h1>
|
|
6
8
|
|
|
7
|
-
<p align="center"
|
|
8
|
-
<p align="center"
|
|
9
|
-
<p align="center">Python 3.8+
|
|
9
|
+
<p align="center">The "security review protocol" before installing any skill: <b>a four-phase checklist (source → code → permissions → risk) + a lightweight checker</b>, with deep-scan handoff to Yuan'an (yotta-security-audit). Use it whenever you fetch a skill from a marketplace, GitHub or any source and want to review it before installation.</p>
|
|
10
|
+
<p align="center">Activates before installing / evaluating any skill, when fetching a skill from a marketplace or GitHub, when reviewing a skill shared by someone else, or in any "about to install unknown code" scenario; also on 审查 / 审查技能 / vetting / 技能安全审查 / 检查技能 — <b>judged by whether unknown code is about to be installed, not keyword luck</b>.</p>
|
|
11
|
+
<p align="center">Python 3.8+ standard library, zero dependency; Windows + Linux; review and report only — the final decision requires human confirmation.</p>
|
|
10
12
|
|
|
11
13
|
<p align="center">
|
|
12
14
|
<a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue" /></a>
|
|
@@ -17,139 +19,152 @@
|
|
|
17
19
|
<a href="https://github.com/YottaMeta/yotta-vetter"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen" /></a>
|
|
18
20
|
</p>
|
|
19
21
|
|
|
20
|
-
##
|
|
22
|
+
## What it is
|
|
21
23
|
|
|
22
|
-
|
|
24
|
+
"Should I install this skill?" deserves a structured, traceable decision basis rather than a gut feeling. Yuanshen turns pre-install review into a four-phase checklist (source → code → permissions → risk) and uses a lightweight checker to scan for dangerous patterns and output a SKILL VETTING REPORT. It is not tied to any single platform: an agent-agnostic review protocol that works in any agent supporting Agent Skills — initial review and report only, never a substitute for the final decision.
|
|
23
25
|
|
|
24
|
-
##
|
|
26
|
+
## Core value
|
|
25
27
|
|
|
26
|
-
- **check
|
|
27
|
-
- **source
|
|
28
|
-
-
|
|
29
|
-
-
|
|
30
|
-
-
|
|
28
|
+
- **check** — four-phase initial review (source / code / permissions / risk) outputting a SKILL VETTING REPORT (verdict / decision record / timestamp / reviewer).
|
|
29
|
+
- **source** — semi-automated GitHub repo source check (stars / last updated / license) with a local cache; gracefully degrades offline.
|
|
30
|
+
- **Shared rules** — dangerous-pattern rules are shared with Yuan'an (scripts/vetter_rules.py is a synced copy of audit_rules.py).
|
|
31
|
+
- **Yuan'an handoff** — when the initial review finds high-and-above findings, it prints a one-line command guiding a Yuan'an deep scan.
|
|
32
|
+
- **Graded verdicts** — critical=DO NOT INSTALL; high=INSTALL WITH CAUTION; medium=REVIEW REQUIRED; low/info=SAFE TO INSTALL.
|
|
31
33
|
|
|
32
|
-
##
|
|
34
|
+
## Why use it
|
|
33
35
|
|
|
34
|
-
|
|
|
36
|
+
| Advantage | Description |
|
|
35
37
|
|---|---|
|
|
36
|
-
|
|
|
37
|
-
|
|
|
38
|
-
|
|
|
39
|
-
|
|
|
40
|
-
|
|
|
41
|
-
|
|
|
42
|
-
|
|
|
38
|
+
| **Four-phase structured** | source → code → permissions → risk, checked ring by ring, none skippable |
|
|
39
|
+
| **Traceable verdicts** | The report carries verdict / decision record / timestamp / reviewer — auditable |
|
|
40
|
+
| **Rules shared with Yuan'an** | vetter_rules.py is a synced copy of audit_rules.py; consistent criteria |
|
|
41
|
+
| **Semi-automated source** | source checks stars / last-updated / license with a local cache; degrades gracefully offline |
|
|
42
|
+
| **Deep-scan handoff** | high-and-above automatically guides you into yotta-security-audit |
|
|
43
|
+
| **Zero dependency** | Python 3.8+ standard library; no daemon / database; Windows + Linux |
|
|
44
|
+
| **Ecosystem distribution** | GitHub + npm synced; install via npx / install.sh / manual copy |
|
|
43
45
|
|
|
44
|
-
##
|
|
46
|
+
## Commands / four-phase review protocol
|
|
45
47
|
|
|
46
|
-
|
|
|
48
|
+
| Phase | Checkpoint | Command / reference |
|
|
47
49
|
|---|---|---|
|
|
48
|
-
| 1.
|
|
49
|
-
| 2.
|
|
50
|
-
| 3.
|
|
51
|
-
| 4.
|
|
50
|
+
| 1. Source | Source platform, author reputation, stars / last-updated, license | source github:owner/repo; references/checklist.md |
|
|
51
|
+
| 2. Code | SKILL.md integrity, script inventory, dangerous-pattern rule scan | check <path> |
|
|
52
|
+
| 3. Permissions | Executable bits, world-writable, symlinks, read/write/network scope | check <path> |
|
|
53
|
+
| 4. Risk | Risk-level verdict + conclusion + decision record | Verdict / decision-record sections of the report |
|
|
52
54
|
|
|
53
|
-
##
|
|
55
|
+
## Verdict matrix
|
|
54
56
|
|
|
55
|
-
|
|
|
57
|
+
| Risk level | Verdict | Action |
|
|
56
58
|
|---|---|---|
|
|
57
|
-
| critical | DO NOT INSTALL |
|
|
58
|
-
| high | INSTALL WITH CAUTION |
|
|
59
|
-
| medium | REVIEW REQUIRED |
|
|
60
|
-
| low/info | SAFE TO INSTALL |
|
|
59
|
+
| critical | DO NOT INSTALL | Refuse installation and review manually |
|
|
60
|
+
| high | INSTALL WITH CAUTION | Decide after manual review |
|
|
61
|
+
| medium | REVIEW REQUIRED | Install after review |
|
|
62
|
+
| low/info | SAFE TO INSTALL | Still recommended to run the full protocol |
|
|
61
63
|
|
|
62
|
-
##
|
|
64
|
+
## Usage examples
|
|
63
65
|
|
|
64
66
|
```bash
|
|
65
|
-
#
|
|
67
|
+
# Initial review of a skill directory
|
|
66
68
|
python3 scripts/yotta_vetter.py check ./some-skill
|
|
67
69
|
|
|
68
|
-
#
|
|
70
|
+
# JSON output + generate a report file
|
|
69
71
|
python3 scripts/yotta_vetter.py check ./some-skill --json --report report.md
|
|
70
72
|
|
|
71
|
-
#
|
|
73
|
+
# Report only high and above
|
|
72
74
|
python3 scripts/yotta_vetter.py check ./some-skill --severity high
|
|
73
75
|
|
|
74
|
-
#
|
|
76
|
+
# Semi-automated source check (local cache; degrades gracefully offline)
|
|
75
77
|
python3 scripts/yotta_vetter.py source github:YottaMeta/yotta-memory
|
|
76
78
|
```
|
|
77
79
|
|
|
78
|
-
**
|
|
80
|
+
**Exit codes**: **0** = clean / low only; **1** = medium; **2** = high; **3** = critical; **4** = error.
|
|
79
81
|
|
|
80
|
-
##
|
|
82
|
+
## Division of labor with Yuan'an
|
|
81
83
|
|
|
82
|
-
-
|
|
83
|
-
-
|
|
84
|
-
-
|
|
84
|
+
- **Yuanshen** = initial review: fast and light — four-phase checklist + rule scan + source check.
|
|
85
|
+
- **Yuan'an** = deep scan: 13 detector classes + system security baseline.
|
|
86
|
+
- When Yuanshen finds high-and-above → it prints a command guiding a Yuan'an deep scan.
|
|
85
87
|
|
|
86
|
-
##
|
|
88
|
+
## Install
|
|
87
89
|
|
|
88
|
-
|
|
90
|
+
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).
|
|
89
91
|
|
|
90
|
-
###
|
|
92
|
+
### Method 1: npm (recommended, one-liner)
|
|
91
93
|
```bash
|
|
92
|
-
#
|
|
94
|
+
# domestic mirror (optional): npm config set registry https://registry.npmmirror.com
|
|
93
95
|
npx -y @yottameta/yotta-vetter -g
|
|
94
|
-
npx -y @yottameta/yotta-vetter --
|
|
95
|
-
npx -y @yottameta/yotta-vetter --dir <你的技能目录> # 任意智能体：指定目录安装
|
|
96
|
+
npx -y @yottameta/yotta-vetter --dir <your-skills-dir> # any agent: install to a specific directory
|
|
96
97
|
```
|
|
97
|
-
>
|
|
98
|
+
> 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-vetter and unpack it to install via method 2 / 3.
|
|
98
99
|
|
|
99
|
-
###
|
|
100
|
+
### Method 2: install.sh one-shot
|
|
100
101
|
```bash
|
|
101
|
-
bash install.sh -g #
|
|
102
|
-
bash install.sh --agent codex #
|
|
103
|
-
bash install.sh #
|
|
102
|
+
bash install.sh -g # user level; bash install.sh --list shows all directories
|
|
103
|
+
bash install.sh --agent codex # specific agent (--list shows available ones)
|
|
104
|
+
bash install.sh # project level: auto-detect existing .claude/.cursor/.codex skills dirs
|
|
104
105
|
bash install.sh --dir /path/to/skills
|
|
105
106
|
```
|
|
106
|
-
>
|
|
107
|
+
> Covers 17 agent families including Trae / Qwen / Comate / CodeBuddy / Kimi. Windows users: works with Git Bash; otherwise use method 3.
|
|
107
108
|
|
|
108
|
-
###
|
|
109
|
-
|
|
109
|
+
### Method 3: manual copy
|
|
110
|
+
Copy the whole `yotta-vetter` folder into the target agent's skills directory. Common locations (user level; Windows uses %USERPROFILE%, Linux/macOS uses ~):
|
|
110
111
|
|
|
111
|
-
|
|
|
112
|
+
| Agent | User-level directory | Project-level directory |
|
|
112
113
|
|---|---|---|
|
|
113
|
-
| Codex |
|
|
114
|
-
| Claude Code |
|
|
115
|
-
| Cursor |
|
|
116
|
-
| Windsurf |
|
|
117
|
-
| opencode |
|
|
118
|
-
| Gemini |
|
|
119
|
-
| Goose |
|
|
120
|
-
| Amp |
|
|
121
|
-
| Kiro |
|
|
122
|
-
| WorkBuddy |
|
|
123
|
-
| Trae Code CLI |
|
|
124
|
-
| Trae IDE
|
|
125
|
-
| Qwen Code |
|
|
126
|
-
| Comate |
|
|
127
|
-
| CodeBuddy |
|
|
128
|
-
| Kimi |
|
|
129
|
-
|
|
|
114
|
+
| Codex | %USERPROFILE%\.codex\skills\yotta-vetter\ | .codex\skills\ |
|
|
115
|
+
| Claude Code | %USERPROFILE%\.claude\skills\yotta-vetter\ | .claude\skills\ |
|
|
116
|
+
| Cursor | %USERPROFILE%\.cursor\skills\yotta-vetter\ | .cursor\skills\ |
|
|
117
|
+
| Windsurf | %USERPROFILE%\.codeium\windsurf\skills\yotta-vetter\ | .windsurf\skills\ |
|
|
118
|
+
| opencode | %USERPROFILE%\.config\opencode\skills\yotta-vetter\ | .opencode\skills\ |
|
|
119
|
+
| Gemini | %USERPROFILE%\.gemini\skills\yotta-vetter\ | .gemini\skills\ |
|
|
120
|
+
| Goose | %USERPROFILE%\.config\goose\skills\yotta-vetter\ | .goose\skills\ |
|
|
121
|
+
| Amp | %USERPROFILE%\.config\agents\skills\yotta-vetter\ | .agents\skills\ |
|
|
122
|
+
| Kiro | %USERPROFILE%\.kiro\skills\yotta-vetter\ | .kiro\skills\ |
|
|
123
|
+
| WorkBuddy | %USERPROFILE%\.workbuddy\skills\yotta-vetter\ | .workbuddy\skills\ |
|
|
124
|
+
| Trae Code CLI | %USERPROFILE%\.traecli\skills\yotta-vetter\ | .traecli\skills\ |
|
|
125
|
+
| Trae IDE (CN) | %USERPROFILE%\.trae-cn\skills\yotta-vetter\ | .trae\skills\ |
|
|
126
|
+
| Qwen Code | %USERPROFILE%\.qwen\skills\yotta-vetter\ | .qwen\skills\ |
|
|
127
|
+
| Comate | %USERPROFILE%\.comate\skills\yotta-vetter\ | .comate\skills\ |
|
|
128
|
+
| CodeBuddy | %USERPROFILE%\.codebuddy\skills\yotta-vetter\ | .codebuddy\skills\ |
|
|
129
|
+
| Kimi | %USERPROFILE%\.kimi\skills\yotta-vetter\ | .kimi\skills\ |
|
|
130
|
+
| Generic AGENTS.md | %USERPROFILE%\.agents\skills\yotta-vetter\ | .agents\skills\ |
|
|
131
|
+
|
|
132
|
+
> 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.
|
|
133
|
+
|
|
134
|
+
## Upgrade / uninstall
|
|
135
|
+
|
|
136
|
+
- **Upgrade**: reinstall the latest version to overwrite — npx -y @yottameta/yotta-vetter -g or rerun bash install.sh -g. Old files inside the skill folder are overwritten; other project files are untouched.
|
|
137
|
+
- **Uninstall**: delete the yotta-vetter folder under the target agent's skills directory (see the table above). The skill stops taking effect after removal.
|
|
138
|
+
|
|
139
|
+
## FAQ
|
|
140
|
+
|
|
141
|
+
- **Can Yuanshen decide for me?** No. The checker only does the initial review and report; the final verdict must be confirmed by a human.
|
|
142
|
+
- **What if high risk is found?** The report prints a guiding command to run Yuan'an (yotta-security-audit) for a deep scan; isolate or stop using the skill first, then review manually.
|
|
143
|
+
- **Does it work offline?** Yes. The GitHub API check in source degrades gracefully without network; check runs fully locally.
|
|
144
|
+
- **Will scanning itself false-positive?** Yuanshen's own source check uses the standard-library urllib to hit the GitHub API, so self-scan hits a network-call hint (medium) — expected behavior, not a risk.
|
|
130
145
|
|
|
131
|
-
|
|
146
|
+
## Related skills
|
|
132
147
|
|
|
133
|
-
|
|
148
|
+
Part of the YottaMeta skill matrix (security family): [yotta-security-audit](https://github.com/YottaMeta/yotta-security-audit) (Yuan'an, 13 detector classes + system security baseline) does the deep scan while Yuanshen does the pre-install review — high-and-above findings guide you into Yuan'an; [yotta-memory](https://github.com/YottaMeta/yotta-memory) (Yuanyi) handles cross-session long-term memory.
|
|
134
149
|
|
|
135
|
-
|
|
136
|
-
- **卸载**：删除目标智能体 skills 目录下的 `yotta-vetter` 文件夹（各智能体目录见上表）即可。卸载后本技能不再生效。
|
|
150
|
+
## Boundaries
|
|
137
151
|
|
|
138
|
-
|
|
152
|
+
- **Initial review & report only** — the checker never replaces the final decision; human confirmation is always required.
|
|
153
|
+
- **Authorized targets only** — source checks hit public GitHub metadata for explicitly named repos; no unauthorized scanning of others' systems.
|
|
154
|
+
- **Offline-capable** — everything except the GitHub source check works fully offline; that check degrades gracefully.
|
|
139
155
|
|
|
140
|
-
|
|
141
|
-
- **发现 high 风险怎么办？** 报告会输出一条引导命令跑元安（yotta-security-audit）深度扫描；建议先隔离或停止使用该技能，再人工复核。
|
|
142
|
-
- **离线能用吗？** 能。source 里 GitHub API 检查在无网络时自动降级；check 完全本地运行。
|
|
143
|
-
- **我自己扫自己会误报吗？** 元审自身含 source 检查，用标准库 urllib 访问 GitHub API，自扫会命中网络调用提示（medium），属预期行为，非风险。
|
|
156
|
+
## Development & validation
|
|
144
157
|
|
|
145
|
-
|
|
158
|
+
- Run at the project root: python tools/validate-skill.py yotta-vetter
|
|
159
|
+
- Tests: python scripts/test_yotta_vetter.py (Windows: python)
|
|
160
|
+
- Details: references/checklist.md, references/vetting-report-template.md
|
|
146
161
|
|
|
147
|
-
|
|
162
|
+
Keep tests green and bump the version before releasing changes.
|
|
148
163
|
|
|
149
|
-
##
|
|
164
|
+
## Changelog
|
|
150
165
|
|
|
151
|
-
|
|
166
|
+
See [CHANGELOG.md](./CHANGELOG.md).
|
|
152
167
|
|
|
153
|
-
##
|
|
168
|
+
## License
|
|
154
169
|
|
|
155
|
-
MIT © YottaMeta
|
|
170
|
+
[MIT](./LICENSE) © YottaMeta. "Yuanshen" / "yotta-vetter" and the YottaMeta family names (yotta-* prefix) are YottaMeta brand identifiers; derived works must not reuse them, see [NOTICE](./NOTICE). The review protocol references open-source skill-vetter style skills; the implementation is YottaMeta's own.
|
package/README.zh-CN.md
ADDED
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
<p align="center"><b>Language</b>: <a href="./README.md">English</a> · 中文</p>
|
|
2
|
+
|
|
3
|
+
<p align="center">
|
|
4
|
+
<img src="assets/banner.png" alt="yotta-vetter banner" width="100%" />
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
<h1 align="center">yotta-vetter · 元审</h1>
|
|
8
|
+
|
|
9
|
+
<p align="center">安装任何技能前的「安全审查协议」：<b>四阶段 checklist（来源 → 代码 → 权限 → 风险）+ 轻量 checker</b>，与元安联动深度扫描。适用于从技能市场、GitHub 或任何来源获取技能、安装前的审查场景。</p>
|
|
10
|
+
<p align="center">检测到安装/评估任何技能前、从市场或 GitHub 获取技能、审查他人分享的技能、任何「要装未知代码」的场景，或用户说 审查 / 审查技能 / vetting / 技能安全审查 / 检查技能 时自动激活——<b>不靠关键词碰运气，按是否要装未知代码判定</b>。</p>
|
|
11
|
+
<p align="center">Python 3.8+ 标准库实现，零依赖；Windows + Linux 通用；只做审查与报告，结论需人工确认。</p>
|
|
12
|
+
|
|
13
|
+
<p align="center">
|
|
14
|
+
<a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue" /></a>
|
|
15
|
+
<a href="https://agentskills.io/"><img alt="Standard: agentskills.io" src="https://img.shields.io/badge/standard-agentskills.io-orange" /></a>
|
|
16
|
+
<a href="https://www.npmjs.com/package/@yottameta/yotta-vetter"><img alt="npm package" src="https://img.shields.io/npm/v/@yottameta/yotta-vetter" /></a>
|
|
17
|
+
<a href="https://github.com/YottaMeta/yotta-vetter"><img alt="GitHub stars" src="https://img.shields.io/github/stars/YottaMeta/yotta-vetter" /></a>
|
|
18
|
+
<a href="https://github.com/YottaMeta/yotta-vetter/commits/main"><img alt="last commit" src="https://img.shields.io/github/last-commit/YottaMeta/yotta-vetter" /></a>
|
|
19
|
+
<a href="https://github.com/YottaMeta/yotta-vetter"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen" /></a>
|
|
20
|
+
</p>
|
|
21
|
+
|
|
22
|
+
## 这是什么
|
|
23
|
+
|
|
24
|
+
「要不要装这个技能」应该有一个结构化、可回溯的决策依据，而不是凭感觉。元审把安装前审查固化成四阶段 checklist（来源 → 代码 → 权限 → 风险），并用轻量 checker 自动扫描危险模式、输出 SKILL VETTING REPORT。它不是某个平台的专属功能，而是一份与智能体无关的审查协议：装进任何支持 Agent Skills 的智能体即可按需调用，只做初审与报告，绝不代替最终决策。
|
|
25
|
+
|
|
26
|
+
## 核心价值
|
|
27
|
+
|
|
28
|
+
- **check**：四阶段初审（来源/代码/权限/风险），输出 SKILL VETTING REPORT（结论/决策记录/时间戳/审查者）。
|
|
29
|
+
- **source**：GitHub 仓库来源半自动化检查（stars/更新时间/许可证），本地缓存，无网络自动降级。
|
|
30
|
+
- **规则共用**：危险模式规则与元安同源（scripts/vetter_rules.py 为 audit_rules.py 的同步副本）。
|
|
31
|
+
- **联动元安**：初审发现 high 及以上，输出一条命令引导跑元安深度扫描。
|
|
32
|
+
- **结论分级**：critical=DO NOT INSTALL；high=INSTALL WITH CAUTION；medium=REVIEW REQUIRED；low/info=SAFE TO INSTALL。
|
|
33
|
+
|
|
34
|
+
## 核心优势
|
|
35
|
+
|
|
36
|
+
| 优势 | 说明 |
|
|
37
|
+
|---|---|
|
|
38
|
+
| **四阶段结构化** | 来源→代码→权限→风险，逐环核对，缺一不可 |
|
|
39
|
+
| **结论可回溯** | 报告含结论/决策记录/时间戳/审查者，留痕可追责 |
|
|
40
|
+
| **规则与元安同源** | vetter_rules.py 为 audit_rules.py 同步副本，口径一致 |
|
|
41
|
+
| **来源半自动** | source 命令查 stars/更新时间/许可证，本地缓存、无网络自动降级 |
|
|
42
|
+
| **联动深度扫描** | high 及以上自动引导跑 yotta-security-audit |
|
|
43
|
+
| **零依赖** | Python 3.8+ 标准库，无 daemon / 无数据库；Windows + Linux 通用 |
|
|
44
|
+
| **生态分发** | GitHub + npm 双源同步发布；npx / install.sh / 手动复制三种安装方式 |
|
|
45
|
+
|
|
46
|
+
## 功能体系 / 四阶段审查协议
|
|
47
|
+
|
|
48
|
+
| 阶段 | 检查点 | 对应命令/参考 |
|
|
49
|
+
|---|---|---|
|
|
50
|
+
| 1. 来源 | 来源平台、作者信誉、stars/更新时间、许可证 | source github:owner/repo；references/checklist.md |
|
|
51
|
+
| 2. 代码 | SKILL.md 完整性、脚本清单、危险模式规则扫描 | check <path> |
|
|
52
|
+
| 3. 权限 | 可执行位、全局可写、符号链接、需读取/写入/联网的范围 | check <path> |
|
|
53
|
+
| 4. 风险 | 风险等级判定 + 结论 + 决策记录 | 报告中的 结论/决策记录 段 |
|
|
54
|
+
|
|
55
|
+
## 结论判定
|
|
56
|
+
|
|
57
|
+
| 风险等级 | 结论 | 动作 |
|
|
58
|
+
|---|---|---|
|
|
59
|
+
| critical | DO NOT INSTALL | 拒绝安装并人工复核 |
|
|
60
|
+
| high | INSTALL WITH CAUTION | 人工复核后决定 |
|
|
61
|
+
| medium | REVIEW REQUIRED | 复核后安装 |
|
|
62
|
+
| low/info | SAFE TO INSTALL | 仍建议按协议完整审查 |
|
|
63
|
+
|
|
64
|
+
## 使用示例
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
# 初审一个技能目录
|
|
68
|
+
python3 scripts/yotta_vetter.py check ./some-skill
|
|
69
|
+
|
|
70
|
+
# 输出 JSON + 生成报告文件
|
|
71
|
+
python3 scripts/yotta_vetter.py check ./some-skill --json --report report.md
|
|
72
|
+
|
|
73
|
+
# 只报告 high 及以上
|
|
74
|
+
python3 scripts/yotta_vetter.py check ./some-skill --severity high
|
|
75
|
+
|
|
76
|
+
# 来源半自动化检查（本地缓存，无网络自动降级）
|
|
77
|
+
python3 scripts/yotta_vetter.py source github:YottaMeta/yotta-memory
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
**exit code 语义**：0 = 干净 / 仅 low；1 = medium；2 = high；3 = critical；4 = 错误。
|
|
81
|
+
|
|
82
|
+
## 与元安的分工
|
|
83
|
+
|
|
84
|
+
- **元审** = 初审：快、轻，四阶段 checklist + 规则扫描 + 来源检查。
|
|
85
|
+
- **元安** = 深度扫描：13 类检测器 + 系统安全基线。
|
|
86
|
+
- 元审发现 high 及以上 → 输出命令引导跑元安深度扫描。
|
|
87
|
+
|
|
88
|
+
## 安装
|
|
89
|
+
|
|
90
|
+
三种方式任选其一，技能文件统一从 **npm** 获取（GitHub 无代理时较慢，npm 可配国内镜像加速）。
|
|
91
|
+
|
|
92
|
+
### 方式一：npm（推荐，一行安装）
|
|
93
|
+
```bash
|
|
94
|
+
# 国内加速（可选）：npm config set registry https://registry.npmmirror.com
|
|
95
|
+
npx -y @yottameta/yotta-vetter -g
|
|
96
|
+
npx -y @yottameta/yotta-vetter --dir <你的技能目录> # 任意智能体：指定目录安装
|
|
97
|
+
```
|
|
98
|
+
> 智能体不在预置列表里？用 `--dir` 指定它的 skills 目录，或手动复制（方式三）。`--list` 可查看各智能体对应的默认目录。想手动拿文件也可 `npm pack @yottameta/yotta-vetter` 解包后按方式二/三安装。
|
|
99
|
+
|
|
100
|
+
### 方式二：install.sh 一键安装
|
|
101
|
+
```bash
|
|
102
|
+
bash install.sh -g # 用户级；bash install.sh --list 查看全部目录
|
|
103
|
+
bash install.sh --agent codex # 指定智能体（--list 可查看可用项）
|
|
104
|
+
bash install.sh # 项目级：自动检测已存在的 .claude/.cursor/.codex 等 skills 目录
|
|
105
|
+
bash install.sh --dir /path/to/skills
|
|
106
|
+
```
|
|
107
|
+
> 覆盖 17 类智能体，含国内 Trae / Qwen / Comate / CodeBuddy / Kimi。Windows 用户：装有 Git Bash 即可用；否则用方式三手动复制。
|
|
108
|
+
|
|
109
|
+
### 方式三：手动复制
|
|
110
|
+
把整个 `yotta-vetter` 文件夹复制到目标智能体的 skills 目录。常见位置（用户级；Windows 用 `%USERPROFILE%`，Linux/macOS 用 `~`）：
|
|
111
|
+
|
|
112
|
+
| 智能体 | 用户级目录 | 项目级目录 |
|
|
113
|
+
|---|---|---|
|
|
114
|
+
| Codex | `%USERPROFILE%\.codex\skills\yotta-vetter\` | `.codex\skills\` |
|
|
115
|
+
| Claude Code | `%USERPROFILE%\.claude\skills\yotta-vetter\` | `.claude\skills\` |
|
|
116
|
+
| Cursor | `%USERPROFILE%\.cursor\skills\yotta-vetter\` | `.cursor\skills\` |
|
|
117
|
+
| Windsurf | `%USERPROFILE%\.codeium\windsurf\skills\yotta-vetter\` | `.windsurf\skills\` |
|
|
118
|
+
| opencode | `%USERPROFILE%\.config\opencode\skills\yotta-vetter\` | `.opencode\skills\` |
|
|
119
|
+
| Gemini | `%USERPROFILE%\.gemini\skills\yotta-vetter\` | `.gemini\skills\` |
|
|
120
|
+
| Goose | `%USERPROFILE%\.config\goose\skills\yotta-vetter\` | `.goose\skills\` |
|
|
121
|
+
| Amp | `%USERPROFILE%\.config\agents\skills\yotta-vetter\` | `.agents\skills\` |
|
|
122
|
+
| Kiro | `%USERPROFILE%\.kiro\skills\yotta-vetter\` | `.kiro\skills\` |
|
|
123
|
+
| WorkBuddy | `%USERPROFILE%\.workbuddy\skills\yotta-vetter\` | `.workbuddy\skills\` |
|
|
124
|
+
| Trae Code CLI | `%USERPROFILE%\.traecli\skills\yotta-vetter\` | `.traecli\skills\` |
|
|
125
|
+
| Trae IDE（国内） | `%USERPROFILE%\.trae-cn\skills\yotta-vetter\` | `.trae\skills\` |
|
|
126
|
+
| Qwen Code | `%USERPROFILE%\.qwen\skills\yotta-vetter\` | `.qwen\skills\` |
|
|
127
|
+
| Comate | `%USERPROFILE%\.comate\skills\yotta-vetter\` | `.comate\skills\` |
|
|
128
|
+
| CodeBuddy | `%USERPROFILE%\.codebuddy\skills\yotta-vetter\` | `.codebuddy\skills\` |
|
|
129
|
+
| Kimi | `%USERPROFILE%\.kimi\skills\yotta-vetter\` | `.kimi\skills\` |
|
|
130
|
+
| 通用 AGENTS.md | `%USERPROFILE%\.agents\skills\yotta-vetter\` | `.agents\skills\` |
|
|
131
|
+
|
|
132
|
+
> Codex 默认目录若设置了环境变量 `CODEX_HOME`，以该变量为准；opencode 若设置 `XDG_CONFIG_HOME` 同理。`.agents\skills` 并非通用目录，仅 OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot 等会读取，**Claude Code 与 Codex 默认不读**。不确定时用 `--dir` 指定，或让该智能体自行安装。
|
|
133
|
+
|
|
134
|
+
## 升级 / 卸载
|
|
135
|
+
|
|
136
|
+
- **升级**：重新安装最新版覆盖即可——`npx -y @yottameta/yotta-vetter -g` 或重跑 `bash install.sh -g`。技能目录内的旧文件会被覆盖；不影响项目中已有的其他文件。
|
|
137
|
+
- **卸载**：删除目标智能体 skills 目录下的 `yotta-vetter` 文件夹（各智能体目录见上表）即可。卸载后本技能不再生效。
|
|
138
|
+
|
|
139
|
+
## 常见问题
|
|
140
|
+
|
|
141
|
+
- **元审能直接替我做决定吗？** 不能。checker 只做初审与报告，最终结论必须由人类确认。
|
|
142
|
+
- **发现 high 风险怎么办？** 报告会输出一条引导命令跑元安（yotta-security-audit）深度扫描；建议先隔离或停止使用该技能，再人工复核。
|
|
143
|
+
- **离线能用吗？** 能。source 里 GitHub API 检查在无网络时自动降级；check 完全本地运行。
|
|
144
|
+
- **我自己扫自己会误报吗？** 元审自身含 source 检查，用标准库 urllib 访问 GitHub API，自扫会命中网络调用提示（medium），属预期行为，非风险。
|
|
145
|
+
|
|
146
|
+
## 相关技能
|
|
147
|
+
|
|
148
|
+
同属 YottaMeta 技能矩阵（安全家族）：[yotta-security-audit](https://github.com/YottaMeta/yotta-security-audit)（元安，13 类检测器 + 系统安全基线）负责深度扫描，元审负责安装前初审——元审发现 high 及以上会引导跑元安；[yotta-memory](https://github.com/YottaMeta/yotta-memory)（元忆）负责跨会话长期记忆。
|
|
149
|
+
|
|
150
|
+
## 开发与校验
|
|
151
|
+
|
|
152
|
+
本项目内运行：`python tools/validate-skill.py yotta-vetter`。
|
|
153
|
+
|
|
154
|
+
## 许可证
|
|
155
|
+
|
|
156
|
+
MIT © YottaMeta —— 详见 [LICENSE](./LICENSE)。品牌声明见 [NOTICE](./NOTICE)。上游来源致谢：审查协议参考开源社区 skill-vetter 类技能思路，实现为 YottaMeta 自有。
|
package/SKILL.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: yotta-vetter
|
|
3
|
-
version: 0.1.
|
|
3
|
+
version: 0.1.4
|
|
4
4
|
description: 元审 —— 安装任何技能前的安全审查协议：四阶段 checklist（来源→代码→权限→风险）+ 轻量 checker，与元安联动深度扫描。触发：安装/评估任何技能前、从市场或 GitHub 获取技能、审查他人分享的技能、任何「要装未知代码」的场景；或用户说 审查/审查技能/vetting/技能安全审查/检查技能 等。边界：checker 只做初审与报告，结论需人工确认；绝不代替最终决策。
|
|
5
5
|
license: MIT
|
|
6
6
|
---
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@yottameta/yotta-vetter",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"description": "元审
|
|
3
|
+
"version": "0.1.4",
|
|
4
|
+
"description": "Yuanshen (元审) — the security review protocol before installing any skill: a four-phase checklist (source → code → permissions → risk) + a lightweight checker, with deep-scan handoff to yotta-security-audit. Triggers before installing/evaluating any skill or reviewing unknown code. Boundaries: initial review & report only; human confirmation required.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"keywords": [
|
|
7
7
|
"agent-skills",
|
|
@@ -21,7 +21,8 @@
|
|
|
21
21
|
"references",
|
|
22
22
|
"scripts",
|
|
23
23
|
"assets",
|
|
24
|
-
"bin"
|
|
24
|
+
"bin",
|
|
25
|
+
"README.zh-CN.md"
|
|
25
26
|
],
|
|
26
27
|
"repository": {
|
|
27
28
|
"type": "git",
|
|
Binary file
|
package/scripts/yotta_vetter.py
CHANGED
|
@@ -48,7 +48,7 @@ _HERE = Path(__file__).resolve().parent
|
|
|
48
48
|
sys.path.insert(0, str(_HERE))
|
|
49
49
|
import vetter_rules # noqa: E402
|
|
50
50
|
|
|
51
|
-
VERSION = "0.1.
|
|
51
|
+
VERSION = "0.1.4"
|
|
52
52
|
TOOL_NAME = "yotta-vetter"
|
|
53
53
|
MAX_FILE_SIZE = 1_000_000
|
|
54
54
|
MAX_LINE_LEN = vetter_rules.MAX_LINE_LEN
|
|
@@ -125,7 +125,7 @@ def collect_files(root):
|
|
|
125
125
|
try:
|
|
126
126
|
if p.suffix.lower() not in TEXT_EXTENSIONS and p.name.lower() not in DOTFILE_NAMES:
|
|
127
127
|
continue
|
|
128
|
-
if p.name in ("audit_rules.py", "vetter_rules.py"):
|
|
128
|
+
if p.name in ("audit_rules.py", "vetter_rules.py", "verify_rules.py"):
|
|
129
129
|
continue # 签名数据文件（规则表）
|
|
130
130
|
if p.stat().st_size > MAX_FILE_SIZE:
|
|
131
131
|
continue
|