feat(skill): 技能治理 v0.2 —— 分桶/调用模式/校验/安全/清单/安装矩阵
- 新增 SCOPE.md 收录门槛 + .out-of-scope/ 拒绝档案 - 生命周期分桶 promoted/beta/deprecated，marketplace 只发布 promoted - 调用模式 model-invoked/user-invoked（user-invoked 不占模型目录） - 新增脚本 validate-skills.py / generate-catalog.py / scan-skill.sh(+allowlist) - 新增 beta 技能 skill-creator、ai-proj-helper-entry、verification-before-completion（各带 evals） - install-skills.sh: --agent dsh / --link / --audit / --include-beta / --no-validate - 融合：dev-review 接收评审意见、req-design 依赖边、agent-swarm 并行编排、dev-test TDD - catalog.json 61 个技能（58 promoted / 3 beta）；validate 0 错误；scan 0 高危；现有测试通过
This commit is contained in:
johnQ
Executable
+161
@@ -0,0 +1,161 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Validate plugins and SKILL.md files against the Agent Skills spec + team rules.
|
||||
|
||||
Usage: python3 scripts/validate-skills.py [--strict]
|
||||
Exit 0 = pass, 1 = errors found.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
ROOT = Path(__file__).resolve().parent.parent
|
||||
ALLOWED_FRONTMATTER = {
|
||||
"name", "description", "license", "compatibility", "metadata",
|
||||
"allowed-tools", "disable-model-invocation", "version",
|
||||
}
|
||||
NAME_RE = re.compile(r"^[a-z0-9][a-z0-9-]{0,63}$")
|
||||
BODY_MAX_BYTES = 20 * 1024
|
||||
DESC_MIN, DESC_MAX = 30, 1024
|
||||
STATUSES = {"promoted", "beta", "deprecated"}
|
||||
INVOCATIONS = {"model-invoked", "user-invoked"}
|
||||
REQUIRED_PLUGIN_FIELDS = ("install_name", "install_type", "dir_category", "version")
|
||||
|
||||
errors: list[str] = []
|
||||
warnings: list[str] = []
|
||||
|
||||
|
||||
def parse_frontmatter(text: str):
|
||||
"""Return (frontmatter dict, body text). Supports one level of nesting."""
|
||||
if not text.startswith("---"):
|
||||
return {}, text
|
||||
end = text.find("\n---", 3)
|
||||
if end == -1:
|
||||
return {}, text
|
||||
raw, body = text[3:end], text[end + 4:]
|
||||
data: dict = {}
|
||||
metadata: dict = {}
|
||||
key = None
|
||||
for line in raw.splitlines():
|
||||
if not line.strip():
|
||||
continue
|
||||
m = re.match(r"^([A-Za-z0-9_-]+):\s*(.*)$", line)
|
||||
if m:
|
||||
key = m.group(1)
|
||||
data[key] = m.group(2).strip().strip('"').strip("'")
|
||||
continue
|
||||
m = re.match(r"^\s+([A-Za-z0-9_-]+):\s*(.*)$", line)
|
||||
if m and key == "metadata":
|
||||
metadata[m.group(1)] = m.group(2).strip().strip('"').strip("'")
|
||||
elif key:
|
||||
data[key] = (data.get(key, "") + " " + line.strip()).strip()
|
||||
if metadata:
|
||||
data["metadata"] = metadata
|
||||
return data, body
|
||||
|
||||
|
||||
def check_plugin(plugin_json: Path):
|
||||
plugin_dir = plugin_json.parent.parent
|
||||
rel = plugin_dir.relative_to(ROOT)
|
||||
try:
|
||||
meta = json.loads(plugin_json.read_text(encoding="utf-8"))
|
||||
except Exception as exc: # noqa: BLE001
|
||||
errors.append(f"{rel}: plugin.json 解析失败: {exc}")
|
||||
return
|
||||
|
||||
for field in REQUIRED_PLUGIN_FIELDS:
|
||||
if not meta.get(field):
|
||||
errors.append(f"{rel}: plugin.json 缺少 {field}")
|
||||
status = meta.get("status", "")
|
||||
if status and status not in STATUSES:
|
||||
errors.append(f"{rel}: status 非法 {status!r}（应为 {sorted(STATUSES)}）")
|
||||
install_name = meta.get("install_name", "")
|
||||
if install_name and not NAME_RE.match(install_name):
|
||||
errors.append(f"{rel}: install_name 不合规 {install_name!r}")
|
||||
|
||||
skills_dir = plugin_dir / "skills"
|
||||
skill_files = sorted(skills_dir.rglob("SKILL.md")) if skills_dir.is_dir() else []
|
||||
if not skill_files:
|
||||
errors.append(f"{rel}: 没有找到 skills/**/SKILL.md")
|
||||
return
|
||||
for skill_md in skill_files:
|
||||
check_skill(rel, skill_md, meta)
|
||||
|
||||
|
||||
def check_skill(rel: Path, skill_md: Path, meta: dict):
|
||||
text = skill_md.read_text(encoding="utf-8", errors="replace")
|
||||
fm, body = parse_frontmatter(text)
|
||||
where = f"{rel}/{skill_md.name}"
|
||||
|
||||
name = fm.get("name", "")
|
||||
if not name:
|
||||
errors.append(f"{where}: frontmatter 缺少 name")
|
||||
elif not NAME_RE.match(name):
|
||||
errors.append(f"{where}: name 不合规 {name!r}（小写字母/数字/连字符，≤64）")
|
||||
|
||||
desc = fm.get("description", "")
|
||||
if not desc:
|
||||
errors.append(f"{where}: frontmatter 缺少 description")
|
||||
elif not (DESC_MIN <= len(desc) <= DESC_MAX):
|
||||
warnings.append(f"{where}: description 长度 {len(desc)}，建议 {DESC_MIN}-{DESC_MAX}（决定是否被触发）")
|
||||
|
||||
for key in fm:
|
||||
if key == "metadata":
|
||||
continue
|
||||
if key not in ALLOWED_FRONTMATTER:
|
||||
warnings.append(f"{where}: 非标准 frontmatter 字段 {key!r}，建议移入 metadata")
|
||||
|
||||
body_bytes = len(body.encode("utf-8"))
|
||||
if body_bytes > BODY_MAX_BYTES:
|
||||
warnings.append(f"{where}: 正文 {body_bytes} 字节，超过 20KB 预算，建议拆 references/")
|
||||
|
||||
metadata = fm.get("metadata") or {}
|
||||
invocation = metadata.get("invocation", "")
|
||||
if invocation and invocation not in INVOCATIONS:
|
||||
errors.append(f"{where}: metadata.invocation 非法 {invocation!r}")
|
||||
disable_model = str(fm.get("disable-model-invocation", "")).lower() == "true"
|
||||
if invocation == "user-invoked" and not disable_model:
|
||||
errors.append(f"{where}: user-invoked 技能必须设置 disable-model-invocation: true")
|
||||
if invocation == "model-invoked" and disable_model:
|
||||
errors.append(f"{where}: model-invoked 技能不应设置 disable-model-invocation: true")
|
||||
|
||||
status = meta.get("status", "")
|
||||
if status == "promoted":
|
||||
docs = ROOT / "docs" / "skills" / f"{meta.get('install_name', name)}.md"
|
||||
if not docs.is_file():
|
||||
warnings.append(f"{where}: promoted 技能缺少四段式文档 docs/skills/{docs.name}")
|
||||
|
||||
# Relative links must resolve.
|
||||
for target in re.findall(r"\]\((\.[^)\s]+|[A-Za-z0-9_-]+/[^)\s]+)\)", body):
|
||||
if target.startswith(("http://", "https://", "#")):
|
||||
continue
|
||||
if not (skill_md.parent / target).exists():
|
||||
warnings.append(f"{where}: 引用的相对路径不存在: {target}")
|
||||
|
||||
|
||||
def main() -> int:
|
||||
strict = "--strict" in sys.argv
|
||||
plugins = sorted(ROOT.glob("skills-*/*-plugin/.claude-plugin/plugin.json"))
|
||||
if not plugins:
|
||||
print("未找到任何 plugin.json", file=sys.stderr)
|
||||
return 1
|
||||
for plugin_json in plugins:
|
||||
check_plugin(plugin_json)
|
||||
|
||||
for warning in warnings:
|
||||
print(f"[warn] {warning}")
|
||||
for error in errors:
|
||||
print(f"[error] {error}")
|
||||
print(f"\n检查 {len(plugins)} 个插件：{len(errors)} 个错误，{len(warnings)} 个警告")
|
||||
if errors:
|
||||
return 1
|
||||
if strict and warnings:
|
||||
print("--strict 模式下，警告视为失败")
|
||||
return 1
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
Reference in New Issue
Block a user