@buaa_smat/hometrans 0.1.0

package/agents/logic-coding/scripts/platform_context_query.py

@@ -0,0 +1,568 @@
+#!/usr/bin/env python3
+"""Minimal platform context query wrapper.
+
+The public contract is provider-neutral:
+  PlatformContextRequest -> platform-context-result.json
+
+Provider details are internal. The script currently supports a DeepWiki-backed
+provider by compiling a small query pack and querying the provider internally.
+It does not summarize evidence or make decisions.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import ssl
+import json
+import random
+import re
+import shutil
+import sys
+import time
+import urllib.error
+import urllib.request
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+from typing import Any
+
+
+DEFAULT_API_LEVEL = 22
+ALLOWED_STAGES = {"planner", "coder"}
+DEFAULT_QUERY_TYPES = ("api", "pattern")
+DEEPWIKI_URL = "https://mcp.deepwiki.com/mcp"
+READ_TIMEOUT_SECONDS = 120
+MAX_RESPONSE_CHARS = 1600
+MAX_WORKERS = 2
+MAX_RETRIES = 2
+RETRY_BASE_SECONDS = 2.0
+DEEPWIKI_REPO = "jjjzzz666/dev_kb_repo"
+PROVIDER_FAILURE_PATTERNS = (
+    "Error processing question",
+    "Query failed",
+    "Error while executing query",
+)
+PLANNER_SLOTS = (
+    "feasibility",
+    "owner_boundary",
+    "forbidden_path",
+    "version_gate",
+    "protocol_variant",
+    "fallback_gap",
+    "blocking_unknown",
+    "completion_evidence",
+    "implementation_implication",
+)
+CODER_SLOTS = (
+    "exact_api",
+    "exact_import",
+    "return_error",
+    "context_permission",
+    "lifecycle_threading",
+    "local_forbidden",
+    "local_validation",
+    "planned_fallback",
+)
+ALLOWED_STRUCTURED_SLOTS = frozenset(PLANNER_SLOTS + CODER_SLOTS)
+PREFACE_PATTERNS = (
+    "you are asking",
+    "you're asking",
+    "i understand",
+    "based on",
+    "summary:",
+    "here are",
+)
+STRUCTURED_LINE_RE = re.compile(
+    r"^[-*]\s*(?:\*\*)?(?P<slot>[a-z][a-z0-9_]*|extra:[a-z0-9_-]+)(?:\*\*)?\s*:\s*(?P<fact>.+)$",
+    re.I,
+)
+
+
+def load_json(path: Path) -> dict[str, Any]:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise SystemExit(f"{path}: invalid JSON: {exc}") from exc
+    if not isinstance(data, dict):
+        raise SystemExit("request must be a JSON object")
+    return data
+
+
+def write_json(path: Path, data: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+
+def normalize(text: Any) -> str:
+    return re.sub(r"\s+", " ", str(text or "").strip())
+
+
+def normalize_list(value: Any, name: str) -> list[str]:
+    if value is None:
+        return []
+    if not isinstance(value, list):
+        raise SystemExit(f"{name} must be a list")
+    return [normalize(item) for item in value if normalize(item)]
+
+
+def resolve_api_level(request: dict[str, Any], cli_api_level: int | None) -> tuple[int, str]:
+    if cli_api_level is not None:
+        return cli_api_level, "cli"
+    raw = request.get("api_level", request.get("api_version"))
+    if raw is not None:
+        try:
+            return int(raw), "request"
+        except (TypeError, ValueError) as exc:
+            raise SystemExit("api_level must be an integer") from exc
+    return DEFAULT_API_LEVEL, "default"
+
+
+def validate_request(request: dict[str, Any], api_level: int) -> dict[str, Any]:
+    stage = normalize(request.get("stage"))
+    if stage not in ALLOWED_STAGES:
+        raise SystemExit("stage must be 'planner' or 'coder'")
+
+    focus_point = normalize(request.get("focus_point"))
+    task_excerpt = normalize(request.get("task_excerpt", request.get("spec_excerpt")))
+    if not focus_point:
+        raise SystemExit("focus_point is required")
+    if not task_excerpt:
+        raise SystemExit("task_excerpt is required")
+
+    project_evidence = normalize(request.get("project_evidence")) or "none"
+    platform_surfaces = normalize_list(request.get("platform_surfaces"), "platform_surfaces")
+    extra_constraints = normalize_list(request.get("extra_constraints"), "extra_constraints")
+    return {
+        "stage": stage,
+        "api_level": api_level,
+        "focus_point": focus_point,
+        "task_excerpt": task_excerpt,
+        "project_evidence": project_evidence,
+        "platform_surfaces": platform_surfaces,
+        "extra_constraints": extra_constraints,
+        "query_types": list(DEFAULT_QUERY_TYPES),
+    }
+
+
+def short_module_name(stage: str, focus_point: str) -> str:
+    base = re.sub(r"[^a-zA-Z0-9]+", "_", focus_point).strip("_").lower()
+    if not base:
+        base = "platform_context"
+    return f"{stage}_{base[:72].rstrip('_')}"
+
+
+def join_items(items: list[str]) -> str:
+    return "; ".join(items) if items else "none"
+
+
+def default_extra_constraints(stage: str) -> list[str]:
+    if stage == "planner":
+        return [
+            "Return only facts that affect feasibility, owner boundary, forbidden path, fallback/gap, edit boundary, blocking unknown, or completion evidence.",
+            "Check API-level gates, capability/permission/signing gates, owner/context/lifecycle constraints, sync/async protocol differences, state/persistence timing, return/error/null/default semantics, forbidden paths, false friends, fallback/gaps, completion evidence, and same-capability different-protocol traps.",
+            "Use the provided platform surfaces as natural signals. Do not require exact API names from the caller, and do not assume the obvious API family is the only valid protocol.",
+        ]
+    return [
+        "Return only facts that affect exact API/import/type/signature/member availability, return/error/null/default/conflict behavior, context/permission/config, lifecycle/threading, local forbidden usage, planned fallback, or local validation.",
+        "Check exact module imports, types, members, signatures, API-level gates, capability/permission/signing gates, owner/context/lifecycle constraints, sync/async protocol differences, state/persistence timing, return/error/null/default/conflict semantics, forbidden paths, false friends, and compile/runtime traps.",
+        "Use the provided platform surfaces as natural signals. Keep the answer local to the approved implementation point; do not redesign the architecture.",
+    ]
+
+
+def build_stage_checks(stage: str, query_type: str) -> str:
+    if stage == "planner":
+        if query_type == "api":
+            return (
+                "path feasibility at this API level; required owner/context/lifecycle/"
+                "capability gate; API family traps that can invalidate the plan; "
+                "fallback or blocking gap; code-observable completion evidence affected by this fact"
+            )
+        if query_type == "migration":
+            return (
+                "cross-platform assumptions that would make the plan invalid; "
+                "HarmonyOS primary path; forbidden migration paths; owner/lifecycle/"
+                "permission differences; fallback or blocking gap"
+            )
+        return (
+            "forbidden paths and false friends; negative space that looks valid but "
+            "should not be used; valid high-level pattern only if it changes the plan; "
+            "hidden owner/lifecycle/state pitfalls; fallback or blocking gap; "
+            "the smallest evidence a planner can require to know the path is complete"
+        )
+
+    if query_type == "api":
+        return (
+            "exact import/module/type/member/signature and minimal call shape; API-level "
+            "availability for this call; required permission/config/context; return/error/"
+            "null/default/conflict semantics; call-site lifecycle/threading constraints; "
+            "compile/runtime failure traps"
+        )
+    if query_type == "migration":
+        return (
+            "old-platform assumptions that would break this local edit; exact HarmonyOS "
+            "replacement API or local pattern; incompatible parameters/return semantics; "
+            "permission/lifecycle differences at this call site"
+        )
+    return (
+        "minimal valid local usage pattern; local forbidden usage that would fail "
+        "compile/runtime; lifecycle/permission/state pitfalls at this call site; "
+        "whether the planned fallback is valid; minimal validation checks for this edit; "
+        "do not redesign the architecture"
+    )
+
+
+def stage_quality_bar(stage: str) -> str:
+    if stage == "planner":
+        return (
+            "Quality bar: a planner can write a short contract from the answer: "
+            "main path, forbidden path, fallback/gap, owner/lifecycle boundary, "
+            "blocking unknown if unresolved, and observable completion evidence. "
+        )
+    return (
+        "Quality bar: a coder can write or check the local code from the answer: "
+        "exact import/module/type/member/signature, minimal call shape, context/"
+        "permission/config, lifecycle/threading, return/error/null/default/conflict "
+        "semantics, forbidden local usage, and validation check. "
+    )
+
+
+def build_query(request: dict[str, Any], query_type: str) -> str:
+    stage_goal = (
+        "choose a valid implementation path before coding"
+        if request["stage"] == "planner"
+        else "verify exact local API usage while implementing"
+    )
+    surfaces = join_items(request["platform_surfaces"])
+    constraints = join_items(request["extra_constraints"] or default_extra_constraints(request["stage"]))
+    checks = build_stage_checks(request["stage"], query_type)
+    slots = ", ".join(PLANNER_SLOTS if request["stage"] == "planner" else CODER_SLOTS)
+
+    return (
+        f"HarmonyOS ArkTS/ArkUI platform fact check. API level: {request['api_level']}. "
+        f"Stage goal: {stage_goal}. Focus: {request['focus_point']}. "
+        f"Task constraint: {request['task_excerpt']}. "
+        f"Project evidence: {request['project_evidence']}. "
+        f"Platform surfaces: {surfaces}. Extra constraints: {constraints}. "
+        f"Check only: {checks}. "
+        f"{stage_quality_bar(request['stage'])}"
+        "Return concise evidence bullets only. "
+        f"Use these slots when applicable: {slots}. "
+        "For critical slots, write `slot: none` when the fact is not applicable or not known. "
+        "If sources disagree or the fact is unavailable, state the conflict or unknown explicitly; do not smooth it over. "
+        "You may add extra:<name> if a critical fact does not fit. "
+        "Do not invent missing facts. "
+        "Max 8 bullets. Format each bullet as '- slot: fact'. "
+        "No preface, headings, examples, tutorials, or steps."
+    )
+
+
+def clean_evidence_response(text: str) -> tuple[str, bool]:
+    lines = [line.strip() for line in text.splitlines()]
+    structured_lines: list[str] = []
+    fallback_lines: list[str] = []
+    for line in lines:
+        if not line:
+            continue
+        lowered = line.lower().lstrip("#*-0123456789. ")
+        if line.startswith("#") or any(lowered.startswith(pattern) for pattern in PREFACE_PATTERNS):
+            continue
+        match = STRUCTURED_LINE_RE.match(line)
+        if match:
+            slot = match.group("slot").lower()
+            fact = match.group("fact").strip()
+            if not fact:
+                continue
+            if slot not in ALLOWED_STRUCTURED_SLOTS and not slot.startswith("extra:"):
+                slot = f"extra:{slot}"
+            structured_lines.append(f"- {slot}: {fact}")
+            continue
+        fallback_lines.append(line)
+    if structured_lines:
+        return "\n".join(structured_lines), True
+    cleaned = "\n".join(fallback_lines).strip()
+    return cleaned or text, False
+
+
+def build_queries(request: dict[str, Any]) -> list[dict[str, str]]:
+    module = short_module_name(request["stage"], request["focus_point"])
+    return [
+        {
+            "module": module,
+            "type": query_type,
+            "query": build_query(request, query_type),
+        }
+        for query_type in request["query_types"]
+    ]
+
+
+def read_cache_entries(path: Path) -> list[dict[str, Any]]:
+    if not path.exists():
+        return []
+    entries: list[dict[str, Any]] = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        if not line.strip():
+            continue
+        try:
+            entry = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(entry, dict):
+            entries.append(entry)
+    return entries
+
+
+def parse_sse_response(content: str) -> str:
+    result = ""
+    for raw_line in content.splitlines():
+        line = raw_line.strip()
+        if not line.startswith("data: "):
+            continue
+        try:
+            data = json.loads(line[6:])
+        except json.JSONDecodeError:
+            continue
+        if "error" in data:
+            return f"[provider_error] {data['error']}"
+        for item in data.get("result", {}).get("content", []):
+            if item.get("type") == "text":
+                result += item.get("text", "")
+    return result.strip()
+
+
+def truncate_response(text: str) -> str:
+    if len(text) <= MAX_RESPONSE_CHARS:
+        return text
+    cut = text.rfind("\n\n", 0, MAX_RESPONSE_CHARS)
+    if cut < MAX_RESPONSE_CHARS * 0.5:
+        cut = MAX_RESPONSE_CHARS
+    return text[:cut].rstrip() + "\n[truncated]"
+
+
+def provider_text_failure(text: str) -> bool:
+    return any(pattern in text for pattern in PROVIDER_FAILURE_PATTERNS)
+
+
+def retry_wait_seconds(attempt: int) -> float:
+    base = RETRY_BASE_SECONDS * (2 ** attempt)
+    return base * (0.8 + 0.4 * random.random())
+
+
+def ask_deepwiki_once(repo: str, question: str) -> tuple[bool, str, bool]:
+    payload = {
+        "jsonrpc": "2.0",
+        "method": "tools/call",
+        "id": 1,
+        "params": {
+            "name": "ask_question",
+            "arguments": {
+                "repoName": repo,
+                "question": question,
+            },
+        },
+    }
+    request = urllib.request.Request(
+        DEEPWIKI_URL,
+        data=json.dumps(payload).encode("utf-8"),
+        headers={
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/event-stream",
+            "User-Agent": "platform-context-query/0.1",
+        },
+        method="POST",
+    )
+    try:
+        context = ssl.create_default_context()
+        with urllib.request.urlopen(request, timeout=READ_TIMEOUT_SECONDS, context=context) as response:
+            text = response.read().decode("utf-8", errors="replace")
+        answer = parse_sse_response(text)
+        if not answer:
+            return False, "[provider_error] empty response", True
+        if answer.startswith("[provider_error]"):
+            return False, answer, True
+        if "429 Too Many Requests" in answer or "Client error '429" in answer:
+            return False, answer, True
+        if provider_text_failure(answer):
+            return False, f"[provider_error] {answer}", True
+        return True, truncate_response(answer), False
+    except urllib.error.HTTPError as exc:
+        return False, f"[http_error] {exc.code} {exc.reason}", exc.code in {429, 500, 502, 503, 504}
+    except urllib.error.URLError as exc:
+        return False, f"[network_error] {exc.reason}", True
+    except TimeoutError:
+        return False, "[timeout]", True
+    except Exception as exc:
+        return False, f"[provider_exception] {type(exc).__name__}: {exc}", False
+
+
+def ask_deepwiki(repo: str, question: str) -> tuple[bool, str]:
+    last_response = ""
+    for attempt in range(MAX_RETRIES + 1):
+        ok, response, retryable = ask_deepwiki_once(repo, question)
+        if ok:
+            return True, response
+        last_response = response
+        if not retryable or attempt >= MAX_RETRIES:
+            break
+        time.sleep(retry_wait_seconds(attempt))
+    return False, last_response
+
+
+def query_one(query: dict[str, str]) -> tuple[bool, dict[str, Any]]:
+    query_type = query.get("type", "pattern")
+    ok, response = ask_deepwiki(DEEPWIKI_REPO, query.get("query", ""))
+    entry = {
+        "ts": dt.datetime.now(dt.timezone.utc).isoformat(timespec="seconds"),
+        "provider": "deepwiki",
+        "repo": DEEPWIKI_REPO,
+        "module": query.get("module", ""),
+        "type": query_type,
+        "query": query.get("query", ""),
+        "response": response,
+        "quality": "verified" if ok else "query_failed",
+    }
+    return ok, entry
+
+
+def run_deepwiki_provider(queries: list[dict[str, str]], cache_path: Path) -> tuple[str, str]:
+    cache_path.parent.mkdir(parents=True, exist_ok=True)
+    stderr_lines: list[str] = []
+    ok_count = 0
+    entries: list[dict[str, Any]] = []
+    with ThreadPoolExecutor(max_workers=min(MAX_WORKERS, len(queries) or 1)) as pool:
+        futures = {pool.submit(query_one, query): query for query in queries}
+        for future in as_completed(futures):
+            query = futures[future]
+            ok, entry = future.result()
+            entries.append(entry)
+            if ok:
+                ok_count += 1
+            else:
+                stderr_lines.append(f"{query.get('module', '')}/{query.get('type', '')}: {entry.get('response', '')}")
+    entries.sort(key=lambda item: str(item.get("type", "")))
+    with cache_path.open("a", encoding="utf-8") as handle:
+        for entry in entries:
+            handle.write(json.dumps(entry, ensure_ascii=False) + "\n")
+    stdout = f"Queried: {ok_count}, Failed: {len(queries) - ok_count}, Total: {len(queries)}"
+    return stdout, "\n".join(stderr_lines)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Query platform context evidence.")
+    parser.add_argument("--request", required=True, help="PlatformContextRequest JSON.")
+    parser.add_argument("--out-dir", required=True, help="Output directory.")
+    parser.add_argument("--api-level", type=int, help="Override API level. Defaults to request.api_level or 22.")
+    parser.add_argument("--dry-run", action="store_true", help="Build files without calling provider.")
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    started = time.time()
+
+    request_path = Path(args.request)
+    out_dir = Path(args.out_dir)
+    provider_dir = out_dir / "provider"
+    result_path = out_dir / "platform-context-result.json"
+    trace_path = out_dir / "platform-context-trace.json"
+    queries_path = provider_dir / "provider-queries.json"
+    cache_path = provider_dir / "provider-cache.jsonl"
+
+    raw_request = load_json(request_path)
+    api_level, api_level_source = resolve_api_level(raw_request, args.api_level)
+    request = validate_request(raw_request, api_level)
+    queries = build_queries(request)
+
+    out_dir.mkdir(parents=True, exist_ok=True)
+    provider_dir.mkdir(parents=True, exist_ok=True)
+    cache_path.unlink(missing_ok=True)
+    shutil.copyfile(request_path, out_dir / "platform-context-request.json")
+    write_json(queries_path, queries)
+
+    status = "dry_run" if args.dry_run else "ok"
+    provider_stdout = ""
+    provider_stderr = ""
+    exit_code = 0
+
+    if not args.dry_run:
+        provider_stdout, provider_stderr = run_deepwiki_provider(queries, cache_path)
+
+    evidence = read_cache_entries(cache_path)
+    verified_count = sum(1 for item in evidence if item.get("quality") == "verified")
+    failed_count = len(evidence) - verified_count
+    structured_missing_count = 0
+    if not args.dry_run:
+        if verified_count == 0:
+            status = "provider_failed"
+            exit_code = 1
+        elif failed_count:
+            status = "partial_ok"
+    elapsed_ms = int((time.time() - started) * 1000)
+
+    evidence_list = []
+    structured_evidence_list = []
+    for item in evidence:
+        raw_response = item.get("response", "")
+        cleaned, structured = clean_evidence_response(str(raw_response))
+        if item.get("quality") == "verified" and not structured:
+            structured_missing_count += 1
+        evidence_list.append({
+            "type": item.get("type", ""),
+            "quality": item.get("quality", ""),
+            "query": item.get("query", ""),
+            "response": raw_response,
+        })
+        structured_evidence_list.append({
+            "type": item.get("type", ""),
+            "quality": item.get("quality", ""),
+            "structured": structured,
+            "response": cleaned,
+        })
+
+    result = {
+        "status": status,
+        "stage": request["stage"],
+        "api_level": api_level,
+        "api_level_source": api_level_source,
+        "focus_point": request["focus_point"],
+        "platform_surfaces": request["platform_surfaces"],
+        "evidence_count": len(evidence),
+        "verified_evidence_count": verified_count,
+        "failed_evidence_count": failed_count,
+        "evidence": evidence_list,
+        "structured_evidence": structured_evidence_list,
+        "structured_missing_count": structured_missing_count,
+        "llm_usage": [
+            "Use evidence only if it changes or confirms the platform contract, local API usage, forbidden path, fallback, blocking unknown, or validation condition.",
+            "If API facts and pattern facts disagree, do not merge them silently. Prefer the stricter lifecycle / permission / forbidden-path constraint; if the implementation path still depends on the disagreement, record blocking Unknown or platform_drift.",
+            "Do not paste raw evidence into plan.md or commit-info.md.",
+            "If status is not ok and the platform fact blocks the task, record blocking Unknown or platform_drift.",
+        ],
+    }
+    trace = {
+        "status": status,
+        "provider": "deepwiki",
+        "api_level": api_level,
+        "api_level_source": api_level_source,
+        "query_count": len(queries),
+        "evidence_count": len(evidence),
+        "verified_evidence_count": verified_count,
+        "failed_evidence_count": failed_count,
+        "structured_missing_count": structured_missing_count,
+        "elapsed_ms": elapsed_ms,
+        "dry_run": bool(args.dry_run),
+        "provider_stdout": provider_stdout,
+        "provider_stderr": provider_stderr,
+        "internal_files": {
+            "queries": str(queries_path),
+            "cache": str(cache_path),
+        },
+    }
+
+    write_json(result_path, result)
+    write_json(trace_path, trace)
+    print(result_path)
+    return exit_code
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())