Skip to content

majiayu000/spellbook / skills/skill-usage-stats

skill-usage-stats

Verified

只读统计 Claude/Codex 的 Skill 使用证据并检查 agent 配置健康。仅用于明确的健康检查、配置诊断、使用排行或低使用候选请求;会识别 enabled 插件并单列批量审计读取。哪些 skill 坏了、互相抢触发、点名却没触发、占用列表预算,或要用历史请求检验改写后的描述,改用 skill-checkup。不要用于规范源、全局/项目/profile/冷存储、投影或退役治理,改用 skill-ecosystem-doctor。忽略引用日志和相邻任务。

scripts/agent_health_core.py

View on GitHub
"""Shared, evidence-bounded helpers for the agent health scanner."""

from __future__ import annotations

import json
import re
import shlex
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any, Iterable


STATUS_ICON = {"ok": "✅", "warn": "⚠️", "fail": "❌", "info": "ℹ️"}


@dataclass(frozen=True)
class ParseIssue:
    """A structured parse or schema error that is safe to render."""

    path: str
    kind: str
    message: str
    line: int | None = None


@dataclass
class Check:
    """One health check and its structured evidence."""

    key: str
    title: str
    status: str = "ok"
    lines: list[str] = field(default_factory=list)
    data: dict[str, object] = field(default_factory=dict)
    errors: list[ParseIssue] = field(default_factory=list)

    def add(self, line: str) -> None:
        self.lines.append(line)

    def add_errors(self, issues: Iterable[ParseIssue]) -> None:
        for issue in issues:
            self.errors.append(issue)
        if self.errors:
            self.status = "fail"
            self.data["parse_error_count"] = len(self.errors)


@dataclass(frozen=True)
class ObjectResult:
    """Result of reading a configuration object."""

    data: dict[str, object] | None
    errors: list[ParseIssue]


@dataclass(frozen=True)
class TranscriptRecord:
    """A parsed JSONL object with source provenance."""

    path: Path
    line: int
    data: dict[str, object]


def msg(lang: str, english: str, chinese: str) -> str:
    return english if lang == "en" else chinese


def object_value(value: object) -> dict[str, object] | None:
    if not isinstance(value, dict):
        return None
    return {str(key): item for key, item in value.items()}


def string_value(value: object) -> str | None:
    return value if isinstance(value, str) else None


def read_json_object(path: Path) -> ObjectResult:
    """Read a JSON object, rejecting invalid JSON and non-object roots."""

    try:
        text = path.read_text(encoding="utf-8")
    except (OSError, UnicodeDecodeError) as exc:
        issue = ParseIssue(str(path), "read_error", str(exc))
        return ObjectResult(None, [issue])
    try:
        raw: Any = json.loads(text)
    except (json.JSONDecodeError, UnicodeDecodeError) as exc:
        line = exc.lineno if isinstance(exc, json.JSONDecodeError) else None
        issue = ParseIssue(str(path), "invalid_json", str(exc), line)
        return ObjectResult(None, [issue])
    data = object_value(raw)
    if data is None:
        issue = ParseIssue(str(path), "non_object_root", "expected a JSON object")
        return ObjectResult(None, [issue])
    return ObjectResult(data, [])


def read_toml_object(path: Path) -> ObjectResult:
    """Read a TOML object when Python's standard TOML parser is available."""

    try:
        import tomllib
    except ModuleNotFoundError:
        issue = ParseIssue(str(path), "unsupported_parser", "Python tomllib is unavailable")
        return ObjectResult(None, [issue])
    try:
        text = path.read_text(encoding="utf-8")
    except (OSError, UnicodeDecodeError) as exc:
        issue = ParseIssue(str(path), "read_error", str(exc))
        return ObjectResult(None, [issue])
    try:
        raw: Any = tomllib.loads(text)
    except (tomllib.TOMLDecodeError, UnicodeDecodeError) as exc:
        issue = ParseIssue(str(path), "invalid_toml", str(exc))
        return ObjectResult(None, [issue])
    data = object_value(raw)
    if data is None:  # Defensive: tomllib currently always returns a dict.
        issue = ParseIssue(str(path), "non_object_root", "expected a TOML table")
        return ObjectResult(None, [issue])
    return ObjectResult(data, [])


def read_frontmatter(path: Path) -> ObjectResult:
    """Read the simple scalar frontmatter fields used by local skill files."""

    try:
        text = path.read_text(encoding="utf-8")
    except (OSError, UnicodeDecodeError) as exc:
        issue = ParseIssue(str(path), "read_error", str(exc))
        return ObjectResult(None, [issue])
    if not text.startswith("---\n"):
        return ObjectResult({}, [])
    end = text.find("\n---", 4)
    if end < 0:
        issue = ParseIssue(str(path), "invalid_frontmatter", "missing closing delimiter")
        return ObjectResult(None, [issue])
    values: dict[str, object] = {}
    errors: list[ParseIssue] = []
    current_key: str | None = None
    block_scalar_key: str | None = None
    for line_number, line in enumerate(text[4:end].splitlines(), start=2):
        if not line.strip() or line.lstrip().startswith("#"):
            continue
        if line[:1].isspace() and current_key is not None:
            if block_scalar_key == current_key:
                fragment = line.strip()
                current = string_value(values.get(current_key)) or ""
                values[current_key] = f"{current} {fragment}".strip()
            continue
        if line.startswith("- ") and current_key is not None and block_scalar_key is None:
            item = line[2:].strip()
            current = values.get(current_key)
            if isinstance(current, list):
                current.append(item)
            elif current in {"", None}:
                values[current_key] = [item]
            else:
                errors.append(ParseIssue(
                    str(path),
                    "invalid_frontmatter",
                    f"sequence item cannot follow scalar key {current_key}",
                    line_number,
                ))
            continue
        match = re.match(r"^([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$", line)
        if match is None:
            errors.append(ParseIssue(
                str(path),
                "invalid_frontmatter",
                "unsupported non-empty frontmatter line",
                line_number,
            ))
            current_key = None
            block_scalar_key = None
            continue
        current_key = match.group(1)
        raw_value = match.group(2).strip()
        if raw_value in {">", ">-", ">+", "|", "|-", "|+"}:
            values[current_key] = ""
            block_scalar_key = current_key
        else:
            values[current_key] = raw_value.strip("'\"")
            block_scalar_key = None
    return ObjectResult(values, errors)


def read_jsonl_objects(paths: Iterable[Path]) -> tuple[list[TranscriptRecord], list[ParseIssue]]:
    """Parse JSONL objects without silently discarding malformed records."""

    records: list[TranscriptRecord] = []
    errors: list[ParseIssue] = []
    for path in paths:
        try:
            lines = path.read_text(encoding="utf-8").splitlines()
        except (OSError, UnicodeDecodeError) as exc:
            errors.append(ParseIssue(str(path), "read_error", str(exc)))
            continue
        for line_number, line in enumerate(lines, start=1):
            if not line.strip():
                continue
            try:
                raw: Any = json.loads(line)
            except json.JSONDecodeError as exc:
                errors.append(ParseIssue(str(path), "invalid_jsonl", str(exc), line_number))
                continue
            data = object_value(raw)
            if data is None:
                errors.append(ParseIssue(
                    str(path), "non_object_record", "expected a JSON object", line_number
                ))
                continue
            records.append(TranscriptRecord(path, line_number, data))
    return records, errors


def recent_files(root: Path, pattern: str, limit: int) -> list[Path]:
    """Return recent files, reporting absence as an empty evidence set."""

    if not root.is_dir():
        return []
    files = [path for path in root.rglob(pattern) if path.is_file()]
    try:
        files.sort(key=lambda path: path.stat().st_mtime, reverse=True)
    except OSError:
        files.sort(key=str)
    return files[:limit]


_SHELL_COMPOSITION = re.compile(r"(?:\n|\r|&&|\|\||[;&|<>`]|\$\()")
_SAFE_SIMPLE = {"pwd", "ls", "which", "wc", "head", "tail", "tree"}
_UNSAFE_GIT_FLAGS = ("--output", "--ext-diff", "--textconv")


def safe_readonly_rule(command: str) -> str | None:
    """Return one exact allow-rule only for a conservative read-only command."""

    stripped = command.strip()
    if (
        not stripped
        or _SHELL_COMPOSITION.search(stripped)
        or any(character in stripped for character in ("$", "*", "?", "[", "]", "{", "}"))
    ):
        return None
    try:
        tokens = shlex.split(stripped, posix=True)
    except ValueError:
        return None
    if not tokens:
        return None
    if tokens[0] == "tree" and any(
        token == "-o" or token.startswith("-o") or token == "--output"
        or token.startswith("--output=")
        for token in tokens[1:]
    ):
        return None
    if any(
        token == flag or token.startswith(f"{flag}=")
        for token in tokens
        for flag in _UNSAFE_GIT_FLAGS
    ):
        return None

    safe = False
    if tokens[0] in _SAFE_SIMPLE:
        safe = tokens[0] != "pwd" or len(tokens) == 1
    elif tokens[0] == "git" and len(tokens) >= 2:
        subcommand = tokens[1]
        if subcommand in {"status", "log", "diff", "show"}:
            safe = True
        elif subcommand == "branch":
            safe = tokens == ["git", "branch", "--list"]
    if not safe:
        return None
    return f"Bash({shlex.join(tokens)})"


def candidate_rules(commands: Iterable[str], minimum_count: int = 2) -> list[str]:
    """Aggregate only exact commands that pass the conservative classifier."""

    counts: dict[str, int] = {}
    for command in commands:
        rule = safe_readonly_rule(command)
        if rule is not None:
            counts[rule] = counts.get(rule, 0) + 1
    return sorted(rule for rule, count in counts.items() if count >= minimum_count)


def semver(value: str) -> tuple[int, ...]:
    base = value.split("+", 1)[0].strip()
    parts = re.findall(r"\d+", base)
    return tuple(int(part) for part in parts[:3]) or (0,)
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall