Claude Code Skills 进阶实战：用渐进式披露架构造一个多文件合规扫描技能

flowchart TD
    A[会话启动] --> B[第1层: 扫描所有 SKILL.md 元数据<br/>name+description, 各30-50 tokens]
    B --> C[用户提问]
    C --> D{模型语义匹配}
    D -->|相关| E[第2层: 加载本技能 SKILL.md 正文]
    D -->|无关| Z[技能保持休眠]
    E --> F{需要确定性计算?}
    F -->|是| G[第3层: 执行 bundled 脚本<br/>代码不进上下文, 仅输出]
    F -->|否| H{需要查细则?}
    H -->|是| I[第3层: 按需读 references/*.md]
    H -->|否| J[生成结果]
    G --> J
    I --> J
    J --> K[填充 assets 模板输出报告]

dep-license-checker/
├── SKILL.md                      # 第2层入口：指令，<500行
├── scripts/
│   └── classify.py               # 第3层：确定性分类器，纯标准库
├── references/
│   ├── license_knowledge.md      # 第3层：SPDX 分类细则，按需加载
│   └── policy_default.md         # 第3层：默认合规策略，按需加载
└── assets/
    └── compliance_report.md      # 第3层：报告模板，按需填充

---
name: dep-license-checker
description: 扫描项目的依赖清单（package.json / requirements.txt / go.mod / Cargo.toml），用确定性脚本将每个依赖的许可证分类为宽松型 / 左版权型 / 未知型，标记违反「仅允许宽松许可证」策略的依赖，并生成 Markdown 合规报告。当用户提到「许可证合规」「license compliance」「检查依赖 license」「GPL/AGPL 风险」「开源许可审查」「引入第三方依赖前检查」时使用。
---

# 依赖许可证合规检查

## 何时触发
用户要把第三方依赖引入项目、或要做开源合规审查、或担心左版权（GPL/AGPL/LGPL/MPL）污染时。

## 执行步骤（务必按顺序）
1. 用 Glob/Grep 找到项目根下的清单文件：`package.json`、`requirements.txt`、`go.mod`、`Cargo.toml`。没有就停止并提示用户。
2. 运行确定性分类器（**首选，代码不进上下文**）：
   `python3 scripts/classify.py <清单文件路径>`
   解析它的 JSON 输出，不要自己用文本去分类。
3. 仅当存在 `copyleft` 或 `unknown` 项、且需要向用户解释某许可证含义时，再去读 `references/license_knowledge.md`。否则跳过以省 token。
4. 仅当用户询问「为什么默认禁止左版权」或要改策略时，才读 `references/policy_default.md`。
5. 把脚本输出填进 `assets/compliance_report.md` 模板，生成最终报告。违规项必须高亮，并给出「替换为宽松许可的替代品」建议。

## 边界
- 不联网。本技能基于本地清单与内置的常见包许可证映射做静态判断。
- 对不在映射表里的包标记为 `unknown`，请用户人工确认，不要臆测许可证。

#!/usr/bin/env python3
"""依赖许可证确定性分类器。纯标准库，输出 JSON。
分类口径：
  permissive = MIT / Apache-2.0 / BSD-* / ISC
  copyleft   = GPL / AGPL / LGPL / MPL
  unknown    = 映射表未覆盖（需人工确认）
退出码：存在 copyleft 违规返回 1，否则 0。
"""
import json, re, sys
from pathlib import Path

# 常见包 -> SPDX 许可证（演示用，可按团队实际扩展）
NPM = {
    "react": "MIT", "react-dom": "MIT", "vue": "MIT", "lodash": "MIT",
    "express": "MIT", "axios": "MIT", "moment": "MIT", "chalk": "MIT",
    "jquery": "MIT", "typescript": "Apache-2.0", "rxjs": "Apache-2.0",
    "elasticsearch": "Apache-2.0", "left-pad": "WTFPL",
    "chart.js": "MIT", "bluebird": "MIT",
}
PY = {
    "requests": "Apache-2.0", "django": "BSD-3-Clause", "flask": "BSD-3-Clause",
    "numpy": "BSD-3-Clause", "pandas": "BSD-3-Clause", "fastapi": "MIT",
    "celery": "BSD-3-Clause", "scipy": "BSD-3-Clause", "pyyaml": "MIT",
    "gunicorn": "MIT", "uvicorn": "BSD-3-Clause",
}
PERMISSIVE = {"MIT", "Apache-2.0", "BSD-2-Clause", "BSD-3-Clause",
              "ISC", "0BSD", "WTFPL", "Unlicense"}

def category(license_id: str) -> str:
    if not license_id:
        return "unknown"
    lid = license_id.upper()
    if lid in {x.upper() for x in PERMISSIVE}:
        return "permissive"
    if re.search(r"\b(GPL|AGPL|LGPL|MPL)\b", lid):
        return "copyleft"
    return "unknown"

def parse_package_json(text):
    data = json.loads(text)
    deps = {**data.get("dependencies", {}), **data.get("devDependencies", {})}
    return [(name, NPM.get(name.lower(), "")) for name in deps]

def parse_requirements(text):
    out = []
    for line in text.splitlines():
        line = line.split("#")[0].strip()
        m = re.match(r"^([A-Za-z0-9_.\-]+)", line)
        if m:
            name = m.group(1).lower()
            out.append((name, PY.get(name, "")))
    return out

def parse_go_mod(text):
    out = []
    for line in text.splitlines():
        m = re.match(r"^\s*(require\s+)?([^\s]+)\s+v[\d.]+", line)
        if m:
            pkg = m.group(2).lower()
            # 粗映射：含 / 的取最后一段
            last = pkg.split("/")[-1]
            out.append((pkg, NPM.get(last) or PY.get(last) or ""))
    return out

PARSERS = {
    "package.json": parse_package_json,
    "requirements.txt": parse_requirements,
    "go.mod": parse_go_mod,
}

def main():
    path = Path(sys.argv[1]) if len(sys.argv) > 1 else None
    if not path or not path.exists():
        print(json.dumps({"error": f"未找到清单文件: {path}"}))
        sys.exit(2)
    parser = PARSERS.get(path.name)
    if not parser:
        print(json.dumps({"error": f"不支持的清单类型: {path.name}"}))
        sys.exit(2)

    result = {"permissive": [], "copyleft": [], "unknown": []}
    for name, lic in parser(path.read_text(encoding="utf-8")):
        cat = category(lic)
        result[cat].append({"name": name, "license": lic or "未声明/未知"})

    violations = result["copyleft"]
    result["summary"] = {
        "total": sum(len(result[k]) for k in ("permissive", "copyleft", "unknown")),
        "violations": len(violations),
        "policy": "仅允许宽松许可证 (MIT/Apache/BSD/ISC)",
        "verdict": "不合规" if violations else "合规",
    }
    print(json.dumps(result, ensure_ascii=False, indent=2))
    sys.exit(1 if violations else 0)

if __name__ == "__main__":
    main()

{
  "permissive": [
    {"name": "react", "license": "MIT"},
    {"name": "lodash", "license": "MIT"},
    {"name": "elasticsearch", "license": "Apache-2.0"}
  ],
  "copyleft": [],
  "unknown": [],
  "summary": {"total": 3, "violations": 0,
              "policy": "仅允许宽松许可证 (MIT/Apache/BSD/ISC)",
              "verdict": "合规"}
}

# 许可证分类细则

## 宽松型（permissive）——通常可放心引入
- MIT / BSD-2 / BSD-3 / ISC / 0BSD：几乎无义务，保留版权声明即可。
- Apache-2.0：需保留 NOTICE 文件，含专利授权条款，企业友好。

## 左版权型（copyleft）——触发「传染」，需法务介入
- GPL：衍生作品必须同样以 GPL 开源。
- AGPL：网络服务也触发开源义务，SaaS 场景高风险。
- LGPL：可作为库链接而不传染，但修改库本身需开源。
- MPL-2.0：文件级 copyleft，比 GPL 弱。

## 未知型（unknown）
映射表未覆盖。处置：去 npm/PyPI 页面或源码 LICENSE 文件人工核实，
**不要由模型猜测**。

# 默认合规策略：仅宽松许可证
- 允许：MIT、Apache-2.0、BSD-2/3、ISC、0BSD、Unlicense
- 禁止：GPL、AGPL、LGPL、MPL（除非走例外审批）
- 未知：阻断引入，待人工确认后更新 scripts/classify.py 的映射表
- 若团队策略不同（如允许 LGPL），在此文件修改即可，无需动脚本

# 依赖许可证合规报告

- 检查范围：{{manifest_file}}
- 依赖总数：{{total}}
- 违规项数：{{violations}}
- 结论：**{{verdict}}**

## 违规依赖（需处理）
{{#each copyleft}}
- ⚠️ `{{name}}` —— 许可证 `{{license}}`，建议替换为等价的宽松许可替代品
{{/each}}

## 合规依赖
{{#each permissive}}
- ✅ `{{name}}` —— `{{license}}`
{{/each}}

## 待人工确认
{{#each unknown}}
- ❓ `{{name}}` —— `{{license}}`
{{/each}}

# 个人级（跨项目可用）
mkdir -p ~/.claude/skills && cp -r dep-license-checker ~/.claude/skills/

# 或项目级（随 git 共享给团队）
mkdir -p .claude/skills && cp -r dep-license-checker .claude/skills/

flowchart LR
    subgraph 构建
      S1[SKILL.md] --- S2[scripts/classify.py]
      S2 --- S3[references/]
      S3 --- S4[assets/]
    end
    S4 --> R[重启 Claude Code]
    R --> D[启动扫描<br/>仅加载 name+description]
    D --> M{用户提问<br/>模型语义匹配}
    M -->|命中| L2[加载 SKILL.md 正文]
    L2 --> EXE[执行 classify.py<br/>仅 JSON 输出进上下文]
    EXE --> REF{需要细则?}
    REF -->|是| RD[按需读 references]
    REF -->|否| TPL
    RD --> TPL[填 assets 模板]
    TPL --> OUT[Markdown 合规报告]
    EV[skill-creator eval<br/>触发率+分类正确率] -.回归.-> S1