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_codex.py

View on GitHub
"""Codex evidence collectors for the cross-tool health scanner."""

from __future__ import annotations

import json
import shutil
import subprocess
from pathlib import Path
from typing import Iterable

from agent_health_core import (
    Check,
    ParseIssue,
    candidate_rules,
    msg,
    object_value,
    read_frontmatter,
    read_json_object,
    read_jsonl_objects,
    read_toml_object,
    safe_readonly_rule,
    string_value,
)


_GUARDIAN_STATUSES = {"in_progress", "approved", "denied", "timed_out", "aborted"}
_GUARDIAN_COMMAND_SOURCES = {"shell", "unified_exec"}


def check_install(lang: str) -> Check:
    check = Check("codex_install", msg(lang, "Codex installation", "Codex 安装"))
    executable = shutil.which("codex")
    version = ""
    if executable is None:
        check.status = "info"
        check.data = {"supported": False, "version": "", "executable": None}
        check.add(msg(lang, "Codex CLI was not found on PATH; filesystem checks remain available.", "PATH 中未找到 Codex CLI;仍会执行文件系统检查。"))
        return check
    try:
        result = subprocess.run(
            ["codex", "--version"], capture_output=True, text=True, timeout=15, check=False
        )
    except (OSError, subprocess.SubprocessError) as exc:
        check.status = "warn"
        check.add(msg(lang, f"Could not run `codex --version`: {exc}", f"无法运行 `codex --version`: {exc}"))
    else:
        if result.returncode == 0:
            version = result.stdout.strip()
        else:
            check.status = "warn"
            check.add(msg(lang, f"`codex --version` exited with status {result.returncode}.", f"`codex --version` 退出码为 {result.returncode}。"))
    check.data = {"supported": True, "version": version, "executable": executable}
    check.add(msg(lang, f"Version {version or 'unknown'}; executable `{executable}`.", f"版本 {version or '未知'};可执行文件 `{executable}`。"))
    return check


def check_config(lang: str, *, path: Path) -> Check:
    check = Check("codex_config", msg(lang, "Codex config.toml", "Codex config.toml"))
    if not path.exists():
        check.status = "info"
        check.data = {"supported": False, "mcp": {}, "parse_error_count": 0}
        check.add(msg(lang, "No config.toml evidence was available; this surface is unsupported.", "没有可用的 config.toml 证据;此检查面不受支持。"))
        return check
    result = read_toml_object(path)
    check.add_errors(result.errors)
    config = result.data or {}
    raw_mcp_value = config.get("mcp_servers")
    raw_mcp = object_value(raw_mcp_value) or {}
    if raw_mcp_value is not None and object_value(raw_mcp_value) is None:
        check.add_errors([ParseIssue(
            str(path), "invalid_field_type", "mcp_servers must be a TOML table"
        )])
    mcp: dict[str, bool] = {}
    for name, raw_server in raw_mcp.items():
        server = object_value(raw_server)
        if server is None:
            check.add_errors([ParseIssue(
                str(path), "invalid_field_type", f"mcp_servers.{name} must be a TOML table"
            )])
            continue
        enabled = server.get("enabled", True) if server is not None else True
        if not isinstance(enabled, bool):
            check.add_errors([ParseIssue(
                str(path), "invalid_field_type", f"mcp_servers.{name}.enabled must be boolean"
            )])
            continue
        mcp[name] = enabled
    check.data.update({
        "supported": result.data is not None,
        "model": string_value(config.get("model")),
        "reasoning": string_value(config.get("model_reasoning_effort")),
        "mcp": mcp,
        "parse_error_count": len(check.errors),
    })
    if check.errors:
        check.add(msg(lang, f"config.toml has {len(check.errors)} parse or schema error(s).", f"config.toml 有 {len(check.errors)} 个解析或结构错误。"))
    else:
        check.add(msg(lang, f"Parsed {len(mcp)} MCP server declaration(s).", f"解析到 {len(mcp)} 个 MCP 服务声明。"))
    return check


def check_skills(lang: str, *, roots: Iterable[Path]) -> Check:
    check = Check("codex_skills", msg(lang, "Codex skill definitions", "Codex 技能定义"))
    existing_roots = [root for root in roots if root.is_dir()]
    definitions: dict[str, list[str]] = {}
    invalid: list[str] = []
    definition_count = 0
    for root in existing_roots:
        for path in root.rglob("SKILL.md"):
            result = read_frontmatter(path)
            check.add_errors(result.errors)
            fields = result.data or {}
            name = string_value(fields.get("name"))
            description = string_value(fields.get("description"))
            definition_count += 1
            if not name or not description:
                invalid.append(str(path))
                continue
            definitions.setdefault(name, []).append(str(path))
    collisions = {name: paths for name, paths in definitions.items() if len(paths) > 1}
    check.data.update({
        "supported": bool(existing_roots),
        "definition_count": definition_count,
        "invalid": invalid,
        "collisions": collisions,
        "parse_error_count": len(check.errors),
    })
    if check.errors:
        check.add(msg(lang, f"Found {len(check.errors)} skill parse error(s).", f"发现 {len(check.errors)} 个技能解析错误。"))
    elif invalid or collisions:
        check.status = "warn"
    elif not existing_roots:
        check.status = "info"
    check.add(msg(lang, f"Found {definition_count} definition(s), {len(invalid)} invalid file(s), and {len(collisions)} declared-name collision(s).", f"发现 {definition_count} 个定义、{len(invalid)} 个无效文件和 {len(collisions)} 个声明名冲突。"))
    if not existing_roots:
        check.add(msg(lang, "No current or legacy skill root was available; this surface is unsupported.", "当前和旧版技能根目录均不可用;此检查面不受支持。"))
    return check


def _parse_exec_command(record_path: Path, line: int, arguments: object) -> tuple[str | None, ParseIssue | None]:
    if not isinstance(arguments, str):
        return None, ParseIssue(str(record_path), "invalid_tool_arguments", "exec_command arguments must be a JSON string", line)
    try:
        raw = json.loads(arguments)
    except json.JSONDecodeError as exc:
        return None, ParseIssue(str(record_path), "invalid_tool_arguments", str(exc), line)
    parsed = object_value(raw)
    if parsed is None:
        return None, ParseIssue(str(record_path), "invalid_tool_arguments", "exec_command arguments must contain an object", line)
    command = string_value(parsed.get("cmd"))
    if command is None:
        return None, ParseIssue(str(record_path), "invalid_tool_arguments", "exec_command arguments are missing string field `cmd`", line)
    return command, None


def _parse_guardian_assessment(
    record_path: Path, line: int, payload: dict[str, object]
) -> tuple[str | None, str | None, str | None, str | None, ParseIssue | None]:
    assessment_id = string_value(payload.get("id"))
    status = string_value(payload.get("status"))
    action = object_value(payload.get("action"))
    if not assessment_id:
        issue = ParseIssue(
            str(record_path), "invalid_record_schema",
            "guardian_assessment is missing string id", line,
        )
        return None, None, None, None, issue
    if status not in _GUARDIAN_STATUSES:
        issue = ParseIssue(
            str(record_path), "invalid_record_schema",
            "guardian_assessment has an unsupported status", line,
        )
        return None, None, None, None, issue
    if action is None or string_value(action.get("type")) is None:
        issue = ParseIssue(
            str(record_path), "invalid_record_schema",
            "guardian_assessment action must be a typed object", line,
        )
        return None, None, None, None, issue
    action_signature = json.dumps(action, sort_keys=True, separators=(",", ":"))
    if action.get("type") != "command":
        return assessment_id, status, action_signature, None, None
    command = string_value(action.get("command"))
    cwd = string_value(action.get("cwd"))
    source = string_value(action.get("source"))
    if not command or not cwd or source not in _GUARDIAN_COMMAND_SOURCES:
        issue = ParseIssue(
            str(record_path), "invalid_record_schema",
            "guardian command action requires source, command, and cwd", line,
        )
        return None, None, None, None, issue
    return assessment_id, status, action_signature, command, None


def _guardian_transition_valid(previous: str, current: str) -> bool:
    return previous == current or previous == "in_progress" and current != "in_progress"


def check_sessions(lang: str, *, paths: Iterable[Path]) -> Check:
    selected = list(paths)
    check = Check("codex_sessions", msg(lang, "Codex local session health", "Codex 本地会话健康度"))
    records, errors = read_jsonl_objects(selected)
    calls: set[tuple[Path, str]] = set()
    assessments: dict[tuple[Path, str], tuple[str, str, str | None]] = {}
    invalid_assessments: set[tuple[Path, str]] = set()
    unmatched_output_count = 0
    duplicate_call_count = 0
    conflicting_assessment_count = 0
    schema_supported = False
    for record in records:
        event_type = string_value(record.data.get("type"))
        raw_payload = record.data.get("payload")
        payload_object = object_value(raw_payload)
        payload = payload_object or {}
        payload_type = string_value(payload.get("type"))
        if event_type == "session_meta":
            schema_supported = True
            if payload_object is None:
                errors.append(ParseIssue(
                    str(record.path), "invalid_record_schema", "session_meta payload must be an object", record.line
                ))
            continue
        if event_type == "event_msg":
            schema_supported = True
            if payload_object is None:
                errors.append(ParseIssue(
                    str(record.path), "invalid_record_schema",
                    "event_msg payload must be an object", record.line,
                ))
                continue
            if payload_type is None:
                errors.append(ParseIssue(
                    str(record.path), "invalid_record_schema",
                    "event_msg payload is missing string type", record.line,
                ))
                continue
            if payload_type != "guardian_assessment":
                continue
            assessment_id, status, action_signature, command, issue = _parse_guardian_assessment(
                record.path, record.line, payload
            )
            if issue is not None:
                errors.append(issue)
                continue
            if assessment_id is not None and status is not None and action_signature is not None:
                assessment_key = (record.path, assessment_id)
                if assessment_key in invalid_assessments:
                    continue
                previous = assessments.get(assessment_key)
                if previous is not None and (
                    previous[1] != action_signature
                    or not _guardian_transition_valid(previous[0], status)
                ):
                    conflicting_assessment_count += 1
                    invalid_assessments.add(assessment_key)
                    assessments.pop(assessment_key, None)
                else:
                    assessments[assessment_key] = (status, action_signature, command)
            continue
        if event_type != "response_item":
            continue
        if payload_object is None:
            schema_supported = True
            errors.append(ParseIssue(
                str(record.path), "invalid_record_schema", "response_item payload must be an object", record.line
            ))
            continue
        if payload_type is None:
            schema_supported = True
            errors.append(ParseIssue(
                str(record.path),
                "invalid_record_schema",
                "response_item payload is missing string type",
                record.line,
            ))
            continue
        if payload_type == "function_call":
            schema_supported = True
            call_id = string_value(payload.get("call_id"))
            if not call_id:
                errors.append(ParseIssue(
                    str(record.path), "invalid_record_schema", "function_call is missing string call_id", record.line
                ))
                continue
            function_name = string_value(payload.get("name"))
            if function_name is None:
                errors.append(ParseIssue(
                    str(record.path), "invalid_record_schema", "function_call is missing string name", record.line
                ))
                continue
            if function_name == "exec_command":
                _, issue = _parse_exec_command(record.path, record.line, payload.get("arguments"))
                if issue is not None:
                    errors.append(issue)
            call_key = (record.path, call_id)
            if call_key in calls:
                duplicate_call_count += 1
            else:
                calls.add(call_key)
        elif payload_type == "function_call_output":
            schema_supported = True
            call_id = string_value(payload.get("call_id"))
            if not call_id:
                errors.append(ParseIssue(
                    str(record.path), "invalid_record_schema", "function_call_output is missing string call_id", record.line
                ))
                continue
            if "output" not in payload:
                errors.append(ParseIssue(
                    str(record.path), "invalid_record_schema", "function_call_output is missing output", record.line
                ))
                continue
            call_key = (record.path, call_id)
            if call_key in calls:
                calls.remove(call_key)
            else:
                unmatched_output_count += 1
        elif payload_type in {"custom_tool_call", "custom_tool_call_output"}:
            schema_supported = True
            call_id = string_value(payload.get("call_id"))
            if payload_type == "custom_tool_call":
                if not call_id:
                    errors.append(ParseIssue(
                        str(record.path), "invalid_record_schema",
                        "custom_tool_call is missing string call_id", record.line,
                    ))
                else:
                    call_key = (record.path, call_id)
                    if call_key in calls:
                        duplicate_call_count += 1
                    else:
                        calls.add(call_key)
            elif not call_id:
                errors.append(ParseIssue(
                    str(record.path), "invalid_record_schema",
                    "custom_tool_call_output is missing string call_id", record.line,
                ))
            elif "output" not in payload:
                errors.append(ParseIssue(
                    str(record.path), "invalid_record_schema",
                    "custom_tool_call_output is missing output", record.line,
                ))
            else:
                call_key = (record.path, call_id)
                if call_key in calls:
                    calls.remove(call_key)
                else:
                    unmatched_output_count += 1

    denied_commands = [
        command
        for status, _, command in assessments.values()
        if status == "denied" and command is not None
    ]
    denial_count = len(denied_commands)
    unpaired_denials = 0
    incomplete_call_count = len(calls)
    incomplete_assessment_count = sum(
        status == "in_progress" for status, _, _ in assessments.values()
    )
    denial_evidence_supported = any(
        command is not None for _, _, command in assessments.values()
    )
    evidence_incomplete = bool(
        incomplete_call_count
        or unmatched_output_count
        or duplicate_call_count
        or incomplete_assessment_count
        or conflicting_assessment_count
    )
    candidates = [] if errors or evidence_incomplete else candidate_rules(denied_commands)
    unsafe_denials = sum(
        1
        for command in denied_commands
        if safe_readonly_rule(command) is None
    )
    check.add_errors(errors)
    check.data.update({
        "supported": bool(selected),
        "schema_supported": schema_supported,
        "transcript_count": len(selected),
        "record_count": len(records),
        "parse_error_count": len(errors),
        "denial_evidence_supported": denial_evidence_supported,
        "incomplete_call_count": incomplete_call_count,
        "unmatched_output_count": unmatched_output_count,
        "duplicate_call_count": duplicate_call_count,
        "incomplete_assessment_count": incomplete_assessment_count,
        "conflicting_assessment_count": conflicting_assessment_count,
        "denial_count": denial_count,
        "unpaired_denial_count": unpaired_denials,
        "unsafe_denial_count": unsafe_denials,
        "candidates": candidates,
    })
    if errors:
        check.add(msg(lang, f"Found {len(errors)} transcript parse or schema error(s).", f"发现 {len(errors)} 个会话解析或结构错误。"))
    elif not selected or not schema_supported:
        check.status = "info"
        check.add(msg(lang, "No verifiable local Codex session schema was available; this surface is unsupported.", "没有可验证的本地 Codex 会话结构;此检查面不受支持。"))
    elif evidence_incomplete:
        check.status = "warn"
        check.add(msg(
            lang,
            f"Denial evidence is incomplete: {incomplete_call_count} call(s) lack output, "
            f"{unmatched_output_count} output(s) lack a prior call, and "
            f"{duplicate_call_count} pending call ID(s) were duplicated; "
            f"{incomplete_assessment_count} guardian assessment(s) are unfinished, and "
            f"{conflicting_assessment_count} guardian lifecycle(s) conflict.",
            f"拒绝证据不完整:{incomplete_call_count} 个调用缺少输出,"
            f"{unmatched_output_count} 个输出缺少先前调用,"
            f"{duplicate_call_count} 个待处理调用 ID 重复;"
            f"{incomplete_assessment_count} 个 guardian 评估尚未结束,"
            f"{conflicting_assessment_count} 个 guardian 生命周期冲突。",
        ))
    elif denial_count:
        check.status = "warn"
    elif not denial_evidence_supported:
        check.status = "info"

    if selected and schema_supported and denial_evidence_supported:
        check.add(msg(lang, f"Observed {denial_count} structured denial(s); {len(candidates)} exact repeated read-only candidate(s).", f"观察到 {denial_count} 次结构化拒绝;{len(candidates)} 个重复且精确的只读候选。"))
    elif selected and schema_supported:
        check.add(msg(
            lang,
            f"Parsed {len(records)} record(s), but no valid structured guardian command lifecycle remained; denial analysis is unsupported.",
            f"解析了 {len(records)} 条记录,但没有保留下有效的结构化 guardian 命令生命周期;拒绝分析不受支持。",
        ))
    for candidate in candidates:
        check.add(candidate)
    return check


def check_context(lang: str, *, paths: Iterable[Path]) -> Check:
    selected = [path for path in paths if path.exists()]
    check = Check("codex_context", msg(lang, "Codex AGENTS.md context", "Codex AGENTS.md 上下文"))
    documents: list[dict[str, object]] = []
    for path in selected:
        try:
            text = path.read_text(encoding="utf-8")
        except (OSError, UnicodeDecodeError) as exc:
            check.add_errors([ParseIssue(str(path), "read_error", str(exc))])
            continue
        documents.append({"path": str(path), "lines": text.count("\n") + 1, "tokens": len(text) // 4})
    check.data.update({"supported": bool(selected), "documents": documents, "parse_error_count": len(check.errors)})
    if not selected:
        check.status = "info"
        check.add(msg(lang, "No AGENTS.md evidence was available; this surface is unsupported.", "没有可用的 AGENTS.md 证据;此检查面不受支持。"))
    else:
        check.add(msg(lang, f"Read {len(documents)} AGENTS.md context file(s).", f"读取了 {len(documents)} 个 AGENTS.md 上下文文件。"))
    return check


def check_plugins(lang: str, *, plugins_dir: Path) -> Check:
    check = Check("codex_plugins", msg(lang, "Codex plugin surfaces", "Codex 插件检查面"))
    if not plugins_dir.is_dir():
        check.status = "info"
        check.data = {"supported": False, "plugin_count": 0, "skill_plugin_count": 0, "mcp_plugin_count": 0, "invalid": [], "parse_error_count": 0}
        check.add(msg(lang, "No plugin cache evidence was available; this surface is unsupported.", "没有可用的插件缓存证据;此检查面不受支持。"))
        return check
    manifests = list(plugins_dir.rglob(".codex-plugin/plugin.json"))
    invalid: list[str] = []
    plugin_count = 0
    skill_plugin_count = 0
    mcp_plugin_count = 0
    for manifest in manifests:
        result = read_json_object(manifest)
        check.add_errors(result.errors)
        data = result.data
        if data is None:
            invalid.append(str(manifest))
            continue
        name = string_value(data.get("name"))
        version = string_value(data.get("version"))
        if not name or not version:
            invalid.append(str(manifest))
        plugin_count += 1
        skills = data.get("skills")
        if skills is not None:
            if isinstance(skills, list):
                if skills:
                    skill_plugin_count += 1
            else:
                check.add_errors([ParseIssue(
                    str(manifest), "invalid_field_type", "skills must be a JSON array"
                )])
        mcp = data.get("mcpServers")
        if mcp is not None:
            if isinstance(mcp, (dict, list)):
                if mcp:
                    mcp_plugin_count += 1
            else:
                check.add_errors([ParseIssue(
                    str(manifest), "invalid_field_type", "mcpServers must be a JSON object or array"
                )])
    check.data.update({
        "supported": True,
        "plugin_count": plugin_count,
        "skill_plugin_count": skill_plugin_count,
        "mcp_plugin_count": mcp_plugin_count,
        "invalid": invalid,
        "parse_error_count": len(check.errors),
    })
    if check.errors:
        check.add(msg(lang, f"Found {len(check.errors)} plugin manifest parse error(s).", f"发现 {len(check.errors)} 个插件清单解析错误。"))
    elif invalid:
        check.status = "warn"
    elif not manifests:
        check.status = "info"
    check.add(msg(lang, f"Found {plugin_count} plugin manifest(s), including {skill_plugin_count} with skills and {mcp_plugin_count} with MCP declarations.", f"发现 {plugin_count} 个插件清单,其中 {skill_plugin_count} 个声明技能,{mcp_plugin_count} 个声明 MCP。"))
    return check
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