Skip to content

OpenSenseNova/SenseNova-Skills / skills/sn-deep-research

sn-deep-research

Unverified

用于用户请求深度研究、系统性研究、竞品分析、方案对比、趋势分析或事实核查时。**遇到以下任一情况就主动使用本 skill,不要自行搜几条就回答**:①用户出现触发词:深度研究 / 深度调研 / 深入研究 / 全面研究 / 系统研究 / 调研 / 调查 / 尽调 / 行业研究 / 市场研究 / 竞品分析 / 政策研究 / 技术研究 / 趋势研究 / 事实核查 / 写一份研究报告 / 调研报告 / 深度报告 / research / deep research;②请求需要跨多来源取证、多维度对比、交叉验证才能给出可靠结论;③用户要求产出报告、白皮书、行业分析或尽调文档;④话题涉及最新政策/市场/产品/价格/法规,需要系统核查。无核验要求的简单常识问答不使用。模糊或宽泛的"研究/了解一下 X"也优先触发。仅不用于:一句话摘要、已给定单一来源的整理、纯文字润色改写。

scripts/validate_supplement_plan.py

View on GitHub
#!/usr/bin/env python3
"""Validate a newly generated supplement_plan.json.

This validator is the Supplement Planner's generation gate. It checks the
plan schema, its binding to plan.json, and the initial work-order state:
every supplement item is pending and has no resolution note. It does not
validate supplement execution or updated evidence.

Usage:
    python3 validate_supplement_plan.py supplement_plan.json \
        --plan plan.json

Exit code:
    0 - pass
    1 - schema or contract errors
    2 - file not found or invalid JSON
"""
from __future__ import annotations

import argparse
import json
import re
import sys
from collections import Counter
from datetime import date
from pathlib import Path


DIM_ID_RE = re.compile(r"^d[1-9]\d*$")
SUPPLEMENT_TYPE_VALUES = {"coverage", "claim_fix", "both"}
SUPPLEMENT_STATUS_VALUES = {
    "pending",
    "resolved",
    "partial",
    "no_data",
    "out_of_scope",
}
DEFERRED_REASON_VALUES = {
    "writing_context_only",
    "low_value",
    "not_actionable",
    "out_of_scope",
    "already_covered",
    "unavailable",
}
TOP_LEVEL_KEYS = {
    "meta",
    "dimension_id",
    "dimension_name",
    "supplement_items",
    "deferred_items",
}
META_KEYS = {"task", "generated_from", "target_report", "date", "principle"}
SUPPLEMENT_ITEM_KEYS = {
    "id",
    "type",
    "gap",
    "question",
    "rationale",
    "suggested_sources",
    "candidate_leads",
    "source_refs",
    "review_refs",
    "impact_if_skipped",
    "status",
    "resolution_note",
}
DEFERRED_ITEM_KEYS = {
    "id",
    "reason",
    "item",
    "source_refs",
    "writing_context_use",
}


def err(rule: str, message: str, **fields: object) -> dict:
    return {"rule": rule, "severity": "error", "message": message, **fields}


def is_nonempty_string(value: object) -> bool:
    return isinstance(value, str) and bool(value.strip())


def validate_keys(
    value: object,
    expected: set[str],
    *,
    location: str,
    rule: str,
) -> tuple[list[dict], dict | None]:
    if not isinstance(value, dict):
        return [err(rule, f"{location} must be an object")], None

    errors: list[dict] = []
    missing = sorted(expected - set(value))
    unknown = sorted(set(value) - expected)
    if missing:
        errors.append(err(rule, f"{location} is missing required fields", missing=missing))
    if unknown:
        errors.append(err(rule, f"{location} contains unknown fields", unknown=unknown))
    return errors, value


def validate_string_array(
    value: object,
    *,
    location: str,
    rule: str,
    min_items: int = 0,
) -> tuple[list[dict], list[str]]:
    if not isinstance(value, list):
        return [err(rule, f"{location} must be an array")], []

    errors: list[dict] = []
    if len(value) < min_items:
        errors.append(
            err(
                rule,
                f"{location} must contain at least {min_items} item(s)",
                length=len(value),
            )
        )

    strings: list[str] = []
    for index, item in enumerate(value):
        if not is_nonempty_string(item):
            errors.append(
                err(rule, f"{location}[{index}] must be a non-empty string", got=item)
            )
        else:
            strings.append(item)

    duplicates = sorted(item for item, count in Counter(strings).items() if count > 1)
    if duplicates:
        errors.append(
            err(rule, f"{location} must not contain duplicates", duplicates=duplicates)
        )
    return errors, strings


def validate(
    data: object,
    plan_data: object | None = None,
) -> list[dict]:
    errors: list[dict] = []
    root_errors, root = validate_keys(
        data,
        TOP_LEVEL_KEYS,
        location="root",
        rule="SP001",
    )
    errors.extend(root_errors)
    if root is None:
        return errors

    meta_errors, meta = validate_keys(
        root.get("meta"),
        META_KEYS,
        location="meta",
        rule="SP002",
    )
    errors.extend(meta_errors)
    if meta is not None:
        for field in ("task", "generated_from", "principle"):
            if not is_nonempty_string(meta.get(field)):
                errors.append(err("SP003", f"meta.{field} must be a non-empty string"))
        if not isinstance(meta.get("target_report"), str):
            errors.append(err("SP003", "meta.target_report must be a string"))
        raw_date = meta.get("date")
        if not is_nonempty_string(raw_date):
            errors.append(err("SP004", "meta.date must use YYYY-MM-DD"))
        else:
            try:
                date.fromisoformat(raw_date)
            except ValueError:
                errors.append(err("SP004", "meta.date must be a real YYYY-MM-DD date",
                                  got=raw_date))

    dimension_id = root.get("dimension_id")
    valid_dimension_id = (
        isinstance(dimension_id, str) and DIM_ID_RE.fullmatch(dimension_id) is not None
    )
    if not valid_dimension_id:
        errors.append(
            err("SP005", "dimension_id must match ^d[1-9]\\d*$", got=dimension_id)
        )
        dimension_id = None

    dimension_name = root.get("dimension_name")
    if not is_nonempty_string(dimension_name):
        errors.append(err("SP006", "dimension_name must be a non-empty string"))

    if plan_data is not None:
        if not isinstance(plan_data, dict):
            errors.append(err("SP007", "plan root must be an object"))
        else:
            dimensions = plan_data.get("dimensions")
            if not isinstance(dimensions, list):
                errors.append(err("SP007", "plan.dimensions must be an array"))
            elif dimension_id is not None:
                planned_dimension = next(
                    (
                        item
                        for item in dimensions
                        if isinstance(item, dict) and item.get("id") == dimension_id
                    ),
                    None,
                )
                if planned_dimension is None:
                    errors.append(
                        err("SP007", f"dimension {dimension_id!r} is not present in plan")
                    )
                elif dimension_name != planned_dimension.get("name"):
                    errors.append(
                        err(
                            "SP008",
                            "dimension_name must exactly match the plan dimension name",
                            expected=planned_dimension.get("name"),
                            got=dimension_name,
                        )
                    )

    supplement_items = root.get("supplement_items")
    if not isinstance(supplement_items, list):
        errors.append(err("SP009", "supplement_items must be an array"))
        supplement_items = []
    elif len(supplement_items) > 8:
        errors.append(
            err("SP009", "supplement_items must contain at most 8 items",
                length=len(supplement_items))
        )

    seen_ids: list[str] = []
    for index, item in enumerate(supplement_items):
        location = f"supplement_items[{index}]"
        item_errors, item_obj = validate_keys(
            item,
            SUPPLEMENT_ITEM_KEYS,
            location=location,
            rule="SP010",
        )
        errors.extend(item_errors)
        if item_obj is None:
            continue

        item_id = item_obj.get("id")
        expected_id_re = (
            re.compile(rf"^{re.escape(dimension_id)}-s[1-9]\d*$")
            if dimension_id is not None
            else None
        )
        if not (
            isinstance(item_id, str)
            and expected_id_re is not None
            and expected_id_re.fullmatch(item_id)
        ):
            errors.append(
                err(
                    "SP011",
                    f"{location}.id must match <dimension_id>-sN",
                    got=item_id,
                )
            )
        else:
            seen_ids.append(item_id)

        item_type = item_obj.get("type")
        if item_type not in SUPPLEMENT_TYPE_VALUES:
            errors.append(
                err(
                    "SP012",
                    f"{location}.type must be one of {sorted(SUPPLEMENT_TYPE_VALUES)}",
                    got=item_type,
                )
            )

        for field in (
            "gap",
            "question",
            "rationale",
            "impact_if_skipped",
        ):
            if not is_nonempty_string(item_obj.get(field)):
                errors.append(
                    err("SP013", f"{location}.{field} must be a non-empty string")
                )

        for field, min_items in (
            ("suggested_sources", 1),
            ("candidate_leads", 0),
            ("source_refs", 1),
            ("review_refs", 0),
        ):
            array_errors, _ = validate_string_array(
                item_obj.get(field),
                location=f"{location}.{field}",
                rule="SP014",
                min_items=min_items,
            )
            errors.extend(array_errors)

        if item_type in {"claim_fix", "both"}:
            review_refs = item_obj.get("review_refs")
            if isinstance(review_refs, list) and not review_refs:
                errors.append(
                    err(
                        "SP015",
                        f"{location}.review_refs must be non-empty for type={item_type}",
                    )
                )

        status = item_obj.get("status")
        if status not in SUPPLEMENT_STATUS_VALUES:
            errors.append(
                err(
                    "SP016",
                    f"{location}.status must be one of "
                    f"{sorted(SUPPLEMENT_STATUS_VALUES)}",
                    got=status,
                )
            )
        elif status != "pending":
            errors.append(
                err(
                    "SP018",
                    f"{location}.status must be pending in a newly generated plan",
                    got=status,
                )
            )

        resolution_note = item_obj.get("resolution_note")
        if not isinstance(resolution_note, str):
            errors.append(err("SP017", f"{location}.resolution_note must be a string"))
        elif resolution_note:
            errors.append(
                err(
                    "SP018",
                    f"{location}.resolution_note must be empty in a newly generated plan",
                )
            )

    deferred_items = root.get("deferred_items")
    if not isinstance(deferred_items, list):
        errors.append(err("SP020", "deferred_items must be an array"))
        deferred_items = []

    for index, item in enumerate(deferred_items):
        location = f"deferred_items[{index}]"
        item_errors, item_obj = validate_keys(
            item,
            DEFERRED_ITEM_KEYS,
            location=location,
            rule="SP021",
        )
        errors.extend(item_errors)
        if item_obj is None:
            continue

        item_id = item_obj.get("id")
        expected_id_re = (
            re.compile(rf"^{re.escape(dimension_id)}-d[1-9]\d*$")
            if dimension_id is not None
            else None
        )
        if not (
            isinstance(item_id, str)
            and expected_id_re is not None
            and expected_id_re.fullmatch(item_id)
        ):
            errors.append(
                err(
                    "SP022",
                    f"{location}.id must match <dimension_id>-dN",
                    got=item_id,
                )
            )
        else:
            seen_ids.append(item_id)

        reason = item_obj.get("reason")
        if reason not in DEFERRED_REASON_VALUES:
            errors.append(
                err(
                    "SP023",
                    f"{location}.reason must be one of {sorted(DEFERRED_REASON_VALUES)}",
                    got=reason,
                )
            )
        if not is_nonempty_string(item_obj.get("item")):
            errors.append(err("SP024", f"{location}.item must be a non-empty string"))
        source_errors, _ = validate_string_array(
            item_obj.get("source_refs"),
            location=f"{location}.source_refs",
            rule="SP025",
            min_items=1,
        )
        errors.extend(source_errors)
        writing_context_use = item_obj.get("writing_context_use")
        if not isinstance(writing_context_use, str):
            errors.append(
                err("SP026", f"{location}.writing_context_use must be a string")
            )
        elif reason == "writing_context_only" and not writing_context_use.strip():
            errors.append(
                err(
                    "SP026",
                    f"{location}.writing_context_use must be non-empty "
                    "for reason=writing_context_only",
                )
            )

    duplicates = sorted(item_id for item_id, count in Counter(seen_ids).items() if count > 1)
    if duplicates:
        errors.append(err("SP027", "item ids must be unique", duplicates=duplicates))

    return errors


def build_stats(data: dict) -> dict:
    supplement_items = [
        item for item in data.get("supplement_items", []) if isinstance(item, dict)
    ]
    return {
        "dimension_id": data.get("dimension_id"),
        "supplement_items": len(supplement_items),
        "deferred_items": len(
            [item for item in data.get("deferred_items", []) if isinstance(item, dict)]
        ),
        "status_distribution": {
            status: sum(1 for item in supplement_items if item.get("status") == status)
            for status in sorted(SUPPLEMENT_STATUS_VALUES)
        },
    }


def load_json(path: Path, label: str) -> tuple[object | None, dict | None]:
    if not path.exists():
        return None, err("FILE", f"File not found: {path}", input=label)
    try:
        return json.loads(path.read_text(encoding="utf-8")), None
    except (OSError, UnicodeError) as exc:
        return None, err("FILE", f"Could not read {path}: {exc}", input=label)
    except json.JSONDecodeError as exc:
        return None, err(
            "JSON",
            f"Invalid {label} JSON: {exc.msg} at line {exc.lineno} col {exc.colno}",
            input=label,
        )


def main() -> None:
    parser = argparse.ArgumentParser(description="Validate a supplement_plan.json file.")
    parser.add_argument("path", help="path to supplement_plan.json")
    parser.add_argument(
        "--plan",
        required=True,
        dest="plan_path",
        help="path to plan.json; validates dimension id and name binding",
    )
    args = parser.parse_args()

    data, load_error = load_json(Path(args.path), "supplement plan")
    if load_error:
        print(json.dumps({"ok": False, "errors": [load_error]},
                         ensure_ascii=False, indent=2))
        sys.exit(2)

    plan_data, load_error = load_json(Path(args.plan_path), "plan")
    if load_error:
        print(json.dumps({"ok": False, "errors": [load_error]},
                         ensure_ascii=False, indent=2))
        sys.exit(2)

    errors = validate(
        data,
        plan_data=plan_data,
    )
    if errors:
        print(json.dumps({"ok": False, "errors": errors}, ensure_ascii=False, indent=2))
        sys.exit(1)

    print(
        json.dumps(
            {"ok": True, "errors": [], "stats": build_stats(data)},
            ensure_ascii=False,
            indent=2,
        )
    )


if __name__ == "__main__":
    main()
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: 472kUpdated 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