@shundoo-ai/dsh-cosmic 1.0.21 → 1.0.22

package/skills/cosmic-build/scripts/query_plugin_handoff.py

@@ -66,7 +66,28 @@ def describe(value: object, pointer: str) -> dict:
     return result
 
 
-def load_handoff(filename: str) -> tuple[Path, dict]:
+def validate_input_files(document: dict) -> None:
+    """准备失败后，旧成功快照不能掩盖已经变化或丢失的输入。"""
+    if not isinstance(document, dict):
+        raise QueryError("HANDOFF_INPUT_INVALID", "handoff must be an object")
+    records = document.get("inputFiles", [])
+    if not isinstance(records, list):
+        raise QueryError("HANDOFF_INPUT_INVALID", "inputFiles must be an array")
+    for record in records:
+        if not isinstance(record, dict) or not isinstance(record.get("path"), str) or not Path(record["path"]).is_absolute():
+            raise QueryError("HANDOFF_INPUT_INVALID", "inputFiles must contain absolute paths and hashes")
+        if not isinstance(record.get("sha256"), str) or len(record["sha256"]) != 64:
+            raise QueryError("HANDOFF_INPUT_INVALID", "inputFiles must contain SHA256 hashes")
+        file = Path(record["path"])
+        try:
+            digest = hashlib.sha256(file.read_bytes()).hexdigest() if file.is_file() else None
+        except OSError as exc:
+            raise QueryError("HANDOFF_INPUT_STALE", f"Prepared input is unreadable: {file}; prepare again") from exc
+        if digest != record["sha256"]:
+            raise QueryError("HANDOFF_INPUT_STALE", f"Prepared input changed or disappeared: {file}; prepare the handoff again before coding or archiving")
+
+
+def load_handoff(filename: str, *, validate_inputs: bool = True) -> tuple[Path, dict]:
     file = Path(filename)
     if not file.is_absolute() or file.suffix.lower() != ".json":
         raise QueryError("HANDOFF_PATH_INVALID", "handoff must be an absolute JSON path returned by preparation")
@@ -78,16 +99,145 @@ def load_handoff(filename: str) -> tuple[Path, dict]:
         raise QueryError("HANDOFF_INVALID", "file is not a successful plugin handoff")
     if not isinstance(document.get("handoffPath"), str) or Path(document["handoffPath"]).resolve() != file.resolve():
         raise QueryError("HANDOFF_PATH_MISMATCH", "handoffPath does not match the selected file")
+    if validate_inputs:
+        validate_input_files(document)
     return file, document
 
 
+def observed_source_gate(handoff: dict) -> dict:
+    """Project the current local gate, never an unfulfilled preparation request."""
+    from plugin_source_gate import gate_path
+
+    requested = handoff.get("sourceGate")
+    if not isinstance(requested, dict):
+        return {}
+    if not handoff.get("projectRoot") or not handoff.get("className"):
+        raise QueryError("HANDOFF_SOURCE_GATE_INVALID", "source gate requires projectRoot and className")
+    expected = Path(gate_path(handoff["projectRoot"], handoff["className"]))
+    if not requested.get("path") or Path(requested["path"]).resolve() != expected.resolve():
+        raise QueryError("HANDOFF_SOURCE_GATE_INVALID", "source gate path does not match this class")
+    try:
+        content = expected.read_text(encoding="utf-8").strip() if expected.is_file() else "missing"
+    except (OSError, UnicodeError) as error:
+        raise QueryError("HANDOFF_SOURCE_GATE_UNAVAILABLE", "cannot read this class's source gate") from error
+    state, _, session = content.partition(":")
+    return {"sourceGate": {**requested, "state": state, "sessionId": session or None,
+                          "verified": state in ("coding", "source_ready"),
+                          "evidenceScope": "Local marker only; session binding still applies to edits, and this is not a compile receipt."}}
+
+
+def report_coding_context(document: dict, operation: str) -> dict:
+    """报表契约独立于运行时表单实体图，保留真实类型证据和精确查询指针。"""
+    from compile_plugin_source import inspect_compile_environment
+
+    handoff = document["handoff"]
+    contract = handoff.get("reportContract")
+    evidence = handoff["codingEvidence"]
+    if not isinstance(contract, dict) or contract.get("formNumber") != handoff.get("formNumber"):
+        raise QueryError("HANDOFF_CODING_CONTEXT_INVALID", "a reportContract for this exact report is required")
+    sections = ("dataSetColumns", "dataSetColumnTypes", "columnPresentation", "filterEnforcement", "filterValueContracts")
+    if "defaultSorts" in contract:
+        sections = (*sections, "defaultSorts")
+    if "defaultSortPolicy" in contract and not isinstance(contract["defaultSortPolicy"], dict):
+        raise QueryError("HANDOFF_CODING_CONTEXT_INVALID", "defaultSortPolicy must be an object")
+    if any(not isinstance(contract.get(key), list) for key in sections):
+        raise QueryError("HANDOFF_CODING_CONTEXT_INVALID", "report contract sections must be arrays")
+    if any(not isinstance(row, dict) for key in sections[1:] for row in contract[key]) or any(not isinstance(row, str) for row in contract[sections[0]]):
+        raise QueryError("HANDOFF_CODING_CONTEXT_INVALID", "report columns must be strings and contract records must be objects")
+    if not isinstance(evidence.get("apiContracts", []), list) or any(not isinstance(row, dict) for row in evidence.get("apiContracts", [])):
+        raise QueryError("HANDOFF_CODING_CONTEXT_INVALID", "apiContracts must be an array of objects")
+    if not isinstance(handoff.get("specialized", {}), dict) or not isinstance(handoff.get("targetSdk", {}), dict):
+        raise QueryError("HANDOFF_CODING_CONTEXT_INVALID", "specialized and targetSdk must be objects")
+    if not isinstance(handoff.get("specialized", {}).get("externalContracts", []), list):
+        raise QueryError("HANDOFF_CODING_CONTEXT_INVALID", "externalContracts must be an array")
+    result = {
+        "status": True, "contextMode": operation, "domain": "report",
+        "handoffPath": document["handoffPath"],
+        "handoffSha256": hashlib.sha256(Path(document["handoffPath"]).read_bytes()).hexdigest(),
+        **{key: handoff[key] for key in ("appRoot", "projectRoot", "formNumber", "type", "className",
+            "sourcePath", "fqcn", "ownershipMode", "existingMethods", "coreLogic", "sourceGate") if key in handoff},
+        **observed_source_gate(handoff),
+        "reportContract": {
+            "path": "/handoff/reportContract",
+            **{key: contract[key] for key in ("schemaVersion", "formNumber", "source", "pluginTypes", "permissionFilterChannel", "defaultSortPolicy") if key in contract},
+            "sections": {key: {"path": f"/handoff/reportContract/{key}", "count": len(contract[key])} for key in sections},
+            **{key: contract[key] for key in sections},
+        },
+        "externalContracts": {"path": "/handoff/specialized/externalContracts",
+            "entities": [entry.get("entity") for entry in handoff.get("specialized", {}).get("externalContracts", [])
+                         if isinstance(entry, dict)]},
+        "codingEvidence": {
+            **{key: evidence[key] for key in ("codingEntry", "signatureTypes", "apiLookup", "sdkLookup", "scenes", "standards", "specializedReferences") if key in evidence},
+            **({"guide": evidence["guide"]} if isinstance(evidence.get("guide"), str) and len(evidence["guide"]) <= 512 else {}),
+            "apiContracts": [{"class": item.get("class"), "path": f"/handoff/codingEvidence/apiContracts/{index}"}
+                             for index, item in enumerate(evidence.get("apiContracts", []))],
+        },
+        "sdkUsage": handoff.get("sdkUsage", []),
+        "targetSdk": {**{key: (handoff.get("targetSdk") or {}).get(key) for key in ("status", "evidenceScope")},
+                      "path": "/handoff/targetSdk"},
+        "stateWarnings": handoff.get("stateWarnings", []),
+        "queryRootEvidence": {"boundary": "Report columns are DataSet output, not persisted query roots; external entities require their own verified contracts."},
+        "evidenceScope": "Design and source facts only; compilation, deployment, filter value classes and runtime behavior are unverified.",
+    }
+    if not result["targetSdk"]["status"]:
+        result["targetSdk"] = {"status": "not-provided"}
+    if operation == "coding-start":
+        result["buildEnvironment"] = inspect_compile_environment(handoff["projectRoot"]) if handoff.get("projectRoot") else {"status": "not-provided"}
+    limit = MAX_CODING_START_BYTES if operation == "coding-start" else MAX_CODING_CONTEXT_BYTES
+    if len(encoded(result).encode("utf-8")) > limit:
+        for key in sections:
+            result["reportContract"].pop(key)
+        result["reportContract"]["detailsOmitted"] = True
+        for key in ("sdkUsage", "existingMethods", "coreLogic"):
+            if key in result:
+                result[key + "Path"] = f"/handoff/{key}"
+                result.pop(key)
+        result["externalContracts"] = {"path": "/handoff/specialized/externalContracts"}
+        result["codingEvidence"] = {"path": "/handoff/codingEvidence"}
+        result["reportContract"].pop("pluginTypes", None)
+        result["stateWarnings"] = {"path": "/handoff/stateWarnings"}
+    return result
+
+
 def query(document: dict, args: argparse.Namespace) -> dict:
+    if args.operation == "runtime-context":
+        from test_environment import plugin_runtime_context
+        handoff = document["handoff"]
+        if not handoff.get("appRoot") or not handoff.get("formNumber"):
+            raise QueryError("HANDOFF_RUNTIME_TARGET_MISSING", "runtime-context requires appRoot and formNumber")
+        return {"status": True, "contextMode": "runtime-context", "runtime": plugin_runtime_context(
+            handoff["appRoot"], handoff["formNumber"], resolve_entry=getattr(args, "resolve_entry", False))}
     if args.operation in ("coding-context", "coding-start"):
         handoff = document["handoff"]
         graph = handoff.get("formGraph")
         evidence = handoff.get("codingEvidence")
-        if not isinstance(graph, dict) or not isinstance(evidence, dict):
-            raise QueryError("HANDOFF_CODING_CONTEXT_INVALID", "formGraph and codingEvidence are required")
+        if not isinstance(evidence, dict):
+            raise QueryError("HANDOFF_CODING_CONTEXT_INVALID", "codingEvidence is required")
+        needs = handoff.get("metadataNeeds")
+        if needs is not None and not (handoff.get("type") in ("reportlist", "report-plugin", "reportform", "reporttreelist") and isinstance(handoff.get("reportContract"), dict)):
+            if not isinstance(needs, list) or any(not isinstance(item, str) or item not in {"form", "list", "entity", "operate"} for item in needs):
+                raise QueryError("HANDOFF_CODING_CONTEXT_INVALID", "metadataNeeds is invalid")
+            if "entity" in needs and not isinstance(graph, dict):
+                raise QueryError("HANDOFF_CODING_CONTEXT_INVALID", "selected entity metadata is missing")
+            if ({"form", "list"} & set(needs)) and not isinstance(handoff.get("uiContext"), dict):
+                raise QueryError("HANDOFF_CODING_CONTEXT_INVALID", "selected page metadata is missing")
+            if "operate" in needs and "operationContracts" not in handoff and "availableOperations" not in handoff:
+                raise QueryError("HANDOFF_CODING_CONTEXT_INVALID", "selected operation metadata is missing")
+        if handoff.get("type") in ("reportlist", "report-plugin", "reportform", "reporttreelist") and isinstance(handoff.get("reportContract"), dict):
+            return report_coding_context(document, args.operation)
+        ui = handoff.get("uiContext")
+        source = handoff.get("sourceContext")
+        operation_context = handoff.get("operationContext")
+        operation_only = (isinstance(operation_context, dict) and operation_context.get("source") == "listOperations"
+                          and operation_context.get("formNumber") == handoff.get("formNumber")
+                          and handoff.get("type") == "operation" and bool(handoff.get("operationKeys")))
+        source_only = (isinstance(source, dict) and source.get("scope") == "source-only"
+                       and source.get("sourcePath") == handoff.get("sourcePath")
+                       and handoff.get("ownershipMode") == "modify" and handoff.get("type") != "operation")
+        if not isinstance(graph, dict) and not source_only and not operation_only and not (isinstance(ui, dict) and ui.get("formNumber") == handoff.get("formNumber") and ui.get("source") == "getFormMetadata"):
+            raise QueryError("HANDOFF_CODING_CONTEXT_INVALID", "verified page context, source context or formGraph is required")
+        if not isinstance(graph, dict):
+            graph = {"entities": []}
         if not isinstance(handoff.get("relatedForms", []), list) or not isinstance(evidence.get("apiContracts", []), list):
             raise QueryError("HANDOFF_CODING_CONTEXT_INVALID", "relatedForms and apiContracts must be arrays")
 
@@ -110,12 +260,20 @@ def query(document: dict, args: argparse.Namespace) -> dict:
             start = {
                 "status": True, "contextMode": "coding-start", "handoffPath": document["handoffPath"],
                 "handoffSha256": hashlib.sha256(Path(document["handoffPath"]).read_bytes()).hexdigest(),
-                **pick(handoff, ("appRoot", "projectRoot", "formNumber", "className", "sourcePath", "fqcn", "operationKeys", "coreLogic", "sourceGate")),
-                "entities": [{**pick(entity, ("entityKey", "role", "collectionProperty", "collectionPath")),
+                "compileCommand": [sys.executable, str(Path(__file__).with_name("compile_plugin_source.py")), "--handoff", document["handoffPath"]],
+                **({"runtimeContextCommand": [sys.executable, str(Path(__file__).resolve()), "runtime-context", "--handoff", document["handoffPath"]]} if not source_only else {}),
+                **({"testCommand": [sys.executable, str(Path(__file__).with_name("run_java_tests.py")), "--project-root", handoff["projectRoot"]]} if handoff.get("projectRoot") else {}),
+                **pick(handoff, ("appRoot", "projectRoot", "formNumber", "className", "sourcePath", "fqcn", "operationKeys", "coreLogic", "sourceGate", "metadataNeeds")),
+                **observed_source_gate(handoff),
+                **({"uiContext": ui} if isinstance(ui, dict) else {}),
+                **({"sourceContext": source} if source_only else {}),
+                **({"operationContext": operation_context} if operation_only else {}),
+                **({"entities": [{**pick(entity, ("entityKey", "role", "collectionProperty", "collectionPath")),
                               "fieldsPath": f"/handoff/formGraph/entities/{index}/fields",
-                              "fields": [pick(field, ("fieldKey", "fieldName", "fieldType", "javaType", "valueAccessor", "idAccessor"))
+                              "fields": [pick(field, ("fieldKey", "fieldName", "fieldType", "javaType", "valueAccessor", "idAccessor", "timeValueUnit", "note"))
                                          for field in entity.get("fields", [])]}
-                             for index, entity in enumerate(graph["entities"])],
+                             for index, entity in enumerate(graph["entities"])]}
+                   if isinstance(handoff.get("formGraph"), dict) else {"entityEvidenceScope": "Entity fields and query roots were not requested and are unverified."}),
                 "relatedForms": [{**pick(form, ("formNumber", "formName", "metadataVersion")),
                                   "path": f"/handoff/relatedForms/{index}"}
                                  for index, form in enumerate(handoff.get("relatedForms", []))],
@@ -127,24 +285,40 @@ def query(document: dict, args: argparse.Namespace) -> dict:
                                        for row in handoff.get("availableOperations", [])
                                        if isinstance(row, dict) and row.get("operationKey") in handoff.get("operationKeys", [])],
                 "stateWarnings": handoff.get("stateWarnings", []),
-                "stateFields": [pick(field, ("fieldKey", "fieldName", "entityKey", "comboOptions")) for field in handoff.get("stateFields", [])],
+                "stateFields": [pick(field, ("fieldKey", "fieldName", "entityKey", "comboOptions"))
+                                for field in handoff.get("stateFields", [])
+                                if field.get("entityKey") in {entity.get("entityKey") for entity in graph["entities"]}],
+                "stateFieldsScope": "Main form only; related-form values remain at /handoff/stateFields",
                 "buildEnvironment": inspect_compile_environment(handoff["projectRoot"]) if handoff.get("projectRoot") else {"status": "not-provided"},
                 "targetSdk": target_sdk(),
-                "codingEvidence": {**pick(evidence, ("codingEntry", "operationDispatch", "apiLookup", "sdkLookup")),
+                "codingEvidence": {**pick(evidence, ("codingEntry", "operationDispatch", "apiLookup", "sdkLookup", "scenes", "standards", "specializedReferences")),
                                    "signatureTypes": [pick(item, ("class", "import")) for item in evidence.get("signatureTypes", [])],
                                    "signatureTypesPath": "/handoff/codingEvidence/signatureTypes",
+                                   "guideSignatures": evidence.get("guideSignatures", []),
                                    **({"guide": evidence["guide"]} if isinstance(evidence.get("guide"), str) and len(evidence["guide"]) <= 512 else {}),
-                                   "apiContracts": [{**pick(contract, ("class",)),
+                                   "apiContracts": [{**pick(contract, ("class", "import")),
                                                      "path": f"/handoff/codingEvidence/apiContracts/{index}",
-                                                     "members": list(dict.fromkeys(member["name"] for member in contract.get("members", []) if "name" in member))}
+                                                     "members": list(dict.fromkeys(member["name"] for member in contract.get("members", []) if "name" in member)),
+                                                     "signatures": [pick(member, ("name", "signature", "declaredBy", "deprecated")) for member in contract.get("members", [])]}
                                                     for index, contract in enumerate(evidence.get("apiContracts", []))]},
+                "specialized": pick(handoff.get("specialized", {}), ("hitModules", "constraints")),
                 "remainingContext": {"stateFields": "/handoff/stateFields", "specialized": "/handoff/specialized", "reportContract": "/handoff/reportContract"},
                 "evidenceScope": "Startup facts and pointers only; collection membership is not proof of a standalone query root, and source compilation does not establish business coverage",
             }
             if len(encoded(start).encode("utf-8")) > MAX_CODING_START_BYTES:
-                for entity in start["entities"]:
+                for entity in start.get("entities", []):
                     entity["fieldCount"] = len(entity.pop("fields"))
                     entity["fieldsOmitted"] = True
+            if len(encoded(start).encode("utf-8")) > MAX_CODING_START_BYTES and isinstance(start.get("uiContext"), dict):
+                page = start["uiContext"]
+                start["uiContext"] = {**pick(page, ("formNumber", "formName", "modelType", "source")),
+                    "controlsPath": "/handoff/uiContext/controls", "controlCount": len(page.get("controls", [])),
+                    "pluginsPath": "/handoff/uiContext/plugins", "pluginCount": len(page.get("plugins", []))}
+            if len(encoded(start).encode("utf-8")) > MAX_CODING_START_BYTES:
+                for contract in start["codingEvidence"]["apiContracts"]:
+                    contract["signaturesOmitted"] = True
+                    contract.pop("signatures", None)
+                start["codingEvidence"].pop("guideSignatures", None)
             return start
 
         def compact_graph(value: dict) -> dict:
@@ -163,27 +337,31 @@ def query(document: dict, args: argparse.Namespace) -> dict:
                 ],
             }
 
-        return {
+        context = {
             "status": True,
             "contextMode": "coding-context",
             "handoffPath": document["handoffPath"],
             "handoffSha256": hashlib.sha256(Path(document["handoffPath"]).read_bytes()).hexdigest(),
-            **pick(handoff, ("appRoot", "projectRoot", "formNumber", "className", "sourcePath", "fqcn", "operationKeys", "coreLogic", "specialized", "sourceGate")),
-            "formGraph": compact_graph(graph),
+            **pick(handoff, ("appRoot", "projectRoot", "formNumber", "className", "sourcePath", "fqcn", "operationKeys", "coreLogic", "specialized", "sourceGate", "metadataNeeds")),
+            **observed_source_gate(handoff),
+            **({"formGraph": compact_graph(graph)} if isinstance(handoff.get("formGraph"), dict) else {}),
+            **({"uiContext": ui} if isinstance(ui, dict) else {}),
+            **({"sourceContext": source} if source_only else {}),
+            **({"operationContext": operation_context} if operation_only else {}),
             "targetSdk": target_sdk(),
-            "queryRootEvidence": {
+            **({"queryRootEvidence": {
                 "formNumber": graph.get("formNumber"),
                 "nonRootEntityKeys": [entity["entityKey"] for entity in graph["entities"]
                                       if entity.get("role") in ("entries", "subentries") and isinstance(entity.get("entityKey"), str)],
                 "boundary": "EntryType and SubEntryType are collection members here, not evidence of standalone QueryServiceHelper roots; runtime query behavior is unverified by this snapshot.",
-            },
+            }} if isinstance(handoff.get("formGraph"), dict) else {"entityEvidenceScope": "Entity fields and query roots were not requested and are unverified."}),
             "relatedForms": [compact_graph(form) for form in handoff.get("relatedForms", [])],
             "operationContracts": handoff.get("operationContracts", []),
             "availableOperations": handoff.get("availableOperations", []),
             "stateFields": handoff.get("stateFields", []),
             "stateWarnings": handoff.get("stateWarnings", []),
             "codingEvidence": {
-                **pick(evidence, ("codingEntry", "signatureTypes", "operationDispatch", "apiLookup", "sdkLookup")),
+                **pick(evidence, ("codingEntry", "signatureTypes", "operationDispatch", "apiLookup", "sdkLookup", "scenes", "standards", "specializedReferences")),
                 **({"guide": evidence["guide"]} if isinstance(evidence.get("guide"), str) and len(evidence["guide"]) <= 512 else {}),
                 "apiContracts": [
                     {
@@ -194,6 +372,12 @@ def query(document: dict, args: argparse.Namespace) -> dict:
                 ],
             },
         }
+        if len(encoded(context).encode("utf-8")) > MAX_CODING_CONTEXT_BYTES and isinstance(context.get("uiContext"), dict):
+            page = context["uiContext"]
+            context["uiContext"] = {**pick(page, ("formNumber", "formName", "modelType", "source")),
+                "controlsPath": "/handoff/uiContext/controls", "controlCount": len(page.get("controls", [])),
+                "pluginsPath": "/handoff/uiContext/plugins", "pluginCount": len(page.get("plugins", []))}
+        return context
     value = resolve_pointer(document, args.path)
     if args.operation == "get":
         return {"status": True, "path": args.path, "value": value}
@@ -216,22 +400,25 @@ def query(document: dict, args: argparse.Namespace) -> dict:
 
 def main() -> int:
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("operation", choices=("index", "find", "get", "coding-context", "coding-start"))
+    parser.add_argument("operation", choices=("index", "find", "get", "coding-context", "coding-start", "runtime-context"))
     parser.add_argument("--handoff", required=True, help="Exact handoffPath returned by prepare_plugin_handoff.py")
     parser.add_argument("--path", default="", help="JSON pointer, such as /handoff/formGraph/entities")
     parser.add_argument("--offset", type=int, default=0, help="First child for index")
     parser.add_argument("--limit", type=int, default=DEFAULT_PAGE_SIZE, help="Children per index page")
     parser.add_argument("--field", help="Direct object field for exact find")
     parser.add_argument("--equals", help="Exact value for find")
+    parser.add_argument("--resolve-entry", action="store_true", help="Resolve a missing runtime entry through the bound platform")
     args = parser.parse_args()
     try:
+        if args.resolve_entry and args.operation != "runtime-context":
+            raise QueryError("HANDOFF_RUNTIME_ARGUMENT_INVALID", "--resolve-entry applies only to runtime-context")
         if args.offset < 0 or not 1 <= args.limit <= MAX_PAGE_SIZE:
             raise QueryError("HANDOFF_PAGE_INVALID", "offset must be nonnegative and limit must be 1–50")
         if args.operation == "find" and (not args.field or args.equals is None or not args.path):
             raise QueryError("HANDOFF_FIND_INVALID", "find requires --path, --field and --equals")
         if args.operation != "find" and (args.field is not None or args.equals is not None):
             raise QueryError("HANDOFF_FIND_INVALID", "--field and --equals apply only to find")
-        if args.operation in ("coding-context", "coding-start") and (args.path or args.offset or args.limit != DEFAULT_PAGE_SIZE):
+        if args.operation in ("coding-context", "coding-start", "runtime-context") and (args.path or args.offset or args.limit != DEFAULT_PAGE_SIZE):
             raise QueryError("HANDOFF_CODING_CONTEXT_ARGUMENT_INVALID", "coding-context accepts only --handoff")
         _, document = load_handoff(args.handoff)
         response = query(document, args)

package/skills/cosmic-build/scripts/register_plugins.py

@@ -78,11 +78,16 @@ def _load_type_owners(root_dir):
 _REGISTRARS = {
     'report-pipeline': (
         'report pipeline (registerReportPlugin)',
-        'Type {type} is registered by the report pipeline (cosmic_api.py registerReportPlugin) '
-        'into the report metadata ReportQueryPlugin slot, not by this API. This script neither '
-        'registered nor verified it: plugin/queryEditable does not return report query plugins. '
-        'The evidence is the report read-back — getReportSchema with design-state evidence, where '
-        '<ReportQueryPlugin> carries the registered class.',
+        'Type {type} is not registered by this API. The report pipeline registers report plugins '
+        'by slot: a reportlist plugin through registerReportPlugin into the report list\'s '
+        'ReportQueryPlugin; a reporttreelist plugin goes into the left tree\'s ReportTreeAp.ReportPlugin '
+        'through setReportProperties --target tree, once a user has added the report tree control. '
+        'A reportform plugin is the report form\'s own form plugin and '
+        'is registered by this script instead, with targetType BILL_FORM. This script neither '
+        'registered nor verified a {type} plugin: '
+        'plugin/queryEditable does not return report query plugins. The evidence is the report '
+        'read-back — getReportSchema with design-state evidence, where <ReportQueryPlugin> carries '
+        'the registered class, and setReportProperties --target tree for the left tree.',
     ),
     'platform-class-discovery': (
         'platform class discovery',
@@ -404,9 +409,9 @@ def main():
         code, _, message = str(exc).partition(':')
         print(json.dumps(_failure(code, message.strip(), writeAttempted=False), ensure_ascii=False))
         return 2
-    server = _load_config(root_dir)
+    server = _load_config(root_dir) if any(type_map.get(c.get('type')) for c in candidates) else None
 
-    if not server:
+    if not server and any(type_map.get(c.get('type')) for c in candidates):
         print(json.dumps(_failure(
             'PLUGIN_SERVER_CONFIG_UNAVAILABLE',
             '~/.kd/config.json not configured or load failed (kd_env_loader)',
@@ -446,7 +451,9 @@ def main():
             results.append({
                 'className': c['className'],
                 'type': plugin_type,
-                'success': True,
+                'success': False,
+                'status': 'routed',
+                'deferred': True,
                 # 与本脚本真正执行过的注册区分开，避免调用方把 success=true 读成
                 # 「已在此处注册并校验」。
                 'registeredHere': False,
@@ -513,6 +520,9 @@ def main():
                     'success': False,
                     'message': str(e),
                 }
+            result['registeredHere'] = result['success']
+            result['verifiedHere'] = False
+            result['formNumber'] = form_number
             if not result['success']:
                 has_failure = True
             else:
@@ -543,13 +553,20 @@ def main():
             if verification['status'] != 'pass':
                 has_failure = True
 
+    if verification and verification.get('checks'):
+        for result in results:
+            result['verifiedHere'] = any(check.get('verified') and _registration_identity(result) ==
+                {key: check[key] for key in ('formNumber', 'className', 'targetType', 'operationKey')}
+                for check in verification['checks'])
+    deferred = sum(1 for result in results if result.get('deferred'))
     output = {
-        'status': 'failed' if has_failure else 'success',
+        'status': 'failed' if has_failure else 'routed' if deferred == len(results) else 'partial' if deferred else 'success',
         'results': results,
         'summary': {
             'total': len(results),
             'success': sum(1 for r in results if r['success']),
-            'failed': sum(1 for r in results if not r['success']),
+            'failed': sum(1 for r in results if not r['success'] and not r.get('deferred')),
+            **({'deferred': deferred} if deferred else {}),
         },
     }
     if source_checks:

package/skills/cosmic-build/scripts/render_output_cards.py

@@ -17,6 +17,7 @@ import json
 import os
 import subprocess
 import sys
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 from urllib.parse import parse_qs, urlparse
@@ -26,10 +27,12 @@ if str(SCRIPT_DIR) not in sys.path:
     sys.path.insert(0, str(SCRIPT_DIR))
 
 from preview_url import PreviewUrlError, get_form_name, get_preview_url
+from _http_client import _is_transient
 from test_environment import export_test_environment
 
 _DYM_BACKGROUND_NOTICE = None
 _TEST_ENVIRONMENT_HANDOFF = None
+_PREVIEW_EVIDENCE = None
 
 
 class ReportPluginSourceMissing(Exception):
@@ -224,6 +227,10 @@ def undelivered_report_plugins(
         except (OSError, ValueError):
             # 契约读不出来，不能当作插件缺失的证据。
             continue
+        # 类要按哪种类型交付，由注册它的槽位决定。pluginTypes 出现之前写的契约只注册取数插件。
+        plugin_types = contract.get("pluginTypes")
+        if not isinstance(plugin_types, dict):
+            plugin_types = {}
         for class_name in contract.get("pluginClasses") or []:
             registered = str(class_name or "").strip()
             if not registered:
@@ -234,6 +241,7 @@ def undelivered_report_plugins(
             missing.append({
                 "formNumber": number,
                 "className": registered,
+                "type": str(plugin_types.get(registered) or "reportlist"),
                 "expectedSource": "src/main/java/" + registered.replace(".", "/") + ".java",
                 "reason": (
                     "no Java source recorded in archive.json" if not recorded
@@ -251,12 +259,13 @@ def _refuse_undelivered(missing: list[dict[str, str]]) -> None:
     for item in missing:
         lines.append(
             f"  {item['formNumber']} registered {item['className']} "
-            f"({item['reason']}); expected source {item['expectedSource']}"
+            f"({item['reason']}); deliver it as type {item.get('type') or 'reportlist'}, "
+            f"expected source {item['expectedSource']}"
         )
     lines.append(
-        "  Registration is metadata only. Deliver the plugin through "
-        "references/java-plugin-delivery.md as type reportlist — generate the source, compile it "
-        "narrowly, and let it reach archive.json — then render the cards."
+        "  Registration is metadata only. Deliver each plugin through "
+        "references/java-plugin-delivery.md as the type named for it — generate the source, "
+        "compile it narrowly, and let it reach archive.json — then render the cards."
     )
     raise ReportPluginSourceMissing("\n".join(lines))
 
@@ -279,14 +288,19 @@ def _join_url(base: str, path: str) -> str:
     return base + path
 
 
-def _archived_preview_urls(artifacts: list[Any]) -> dict[str, str]:
+def _archived_preview_urls(artifacts: list[Any], base_url: str = "") -> dict[str, str]:
     """formNumber -> 早前成功运行归档的预览链接（getPreviewUrl 失败时兜底）。"""
     urls: dict[str, str] = {}
     for artifact in artifacts:
         if not isinstance(artifact, dict):
             continue
         raw_url = str(artifact.get("url") or "").strip()
-        if not raw_url:
+        parsed = urlparse(raw_url)
+        base = urlparse(base_url)
+        if not raw_url or parsed.scheme not in ("http", "https") or not parsed.netloc or parsed.username or parsed.password:
+            continue
+        if base_url and (parsed.scheme != base.scheme or parsed.netloc != base.netloc or
+                         not (parsed.path == base.path or parsed.path.startswith(base.path.rstrip("/") + "/"))):
             continue
         form_number = _artifact_form_number(artifact)
         if form_number:
@@ -346,8 +360,9 @@ def render(
 ) -> list[str]:
     global _DYM_BACKGROUND_NOTICE
     _DYM_BACKGROUND_NOTICE = None
-    global _TEST_ENVIRONMENT_HANDOFF
+    global _TEST_ENVIRONMENT_HANDOFF, _PREVIEW_EVIDENCE
     _TEST_ENVIRONMENT_HANDOFF = None
+    _PREVIEW_EVIDENCE = {}
     archive_path = Path(app_root) / "archive.json"
     if not archive_path.exists():
         print(f"Warning: {archive_path} does not exist, skipping kdform cards", file=sys.stderr)
@@ -420,7 +435,7 @@ def render(
             _TEST_ENVIRONMENT_HANDOFF = export_test_environment(
                 app_root, server_config, [number for number, _title in form_entries]
             )
-            archived_urls = _archived_preview_urls(artifacts)
+            archived_urls = _archived_preview_urls(artifacts, base_url)
             # 子集渲染不能清掉其他表单已经归档的卡片。
             requested_set = {fn for fn, _title in form_entries}
             artifacts = [
@@ -432,34 +447,46 @@ def render(
 
             for fn, title in form_entries:
                 if title == fn:
-                    title = get_form_name(server_config, base_url, fn) or title
+                    try:
+                        title = get_form_name(server_config, base_url, fn) or title
+                    except Exception:
+                        # 名称读取失败只降级标题，不阻断目标报表卡片。
+                        print(f"Warning: form name lookup failed for {fn}; using its exact form number", file=sys.stderr)
                 api_ids = api_ids_map.get(fn, [])
                 if isinstance(api_ids, list):
                     api_ids_str = ",".join(str(i) for i in api_ids)
                 else:
                     api_ids_str = str(api_ids)
 
+                preview = {"status": "fresh", "runtimeVerified": False,
+                           "checkedAt": datetime.now(timezone.utc).isoformat()}
                 try:
                     url = get_preview_url(server_config, base_url, fn)
                 except Exception as e:
                     if "FORM_NOT_FOUND" in str(e).upper():
                         deleted_numbers.append(fn)
                         print(
-                            f"提示：{fn} 已不存在；已移除归档卡片且不生成替代卡片",
+                            f"Notice: {fn} no longer exists; removed its archived card and emitted no replacement",
                             file=sys.stderr,
                         )
                         continue
                     # getPreviewUrl 瞬时失败不能丢掉整个回复的卡片。
-                    url = archived_urls.get(fn, "")
-                    fallback = "reusing archived preview link" if url else "rendering card without preview link"
-                    print(f"Warning: getPreviewUrl({fn}) failed ({e}); {fallback}", file=sys.stderr)
+                    http_status = getattr(e, "code", None)
+                    url = archived_urls.get(fn, "") if _is_transient(e) else ""
+                    preview.update(status="archived" if url else "unavailable", errorType=type(e).__name__)
+                    if isinstance(http_status, int):
+                        preview["httpStatus"] = http_status
+                    preview["retryable"] = _is_transient(e)
+                    fallback = "reusing archived preview link (not a fresh preview verification)" if url else "rendering card without preview link"
+                    print(f"Warning: getPreviewUrl({fn}) failed; {fallback}", file=sys.stderr)
                 # 平台忽略 viewType=list 时，由已验证列表元数据恢复标准 bos_list 入口。
                 try:
                     list_url = get_preview_url(
                         server_config, base_url, fn, view_type="list", form_preview_url=url,
-                    )
-                except Exception:
+                    ) if preview["status"] == "fresh" else ""
+                except Exception as exc:
                     list_url = ""
+                    preview["listErrorType"] = type(exc).__name__
                 if list_url and list_url == url:
                     print(
                         f"Warning: getPreviewUrl({fn}, viewType=list) returned the editor URL; omitted listUrl",
@@ -474,6 +501,8 @@ def render(
                 card = {"title": title, "url": url, "metadata": metadata, "plugins": plugins, "designer": designer}
                 if list_url:
                     card["listUrl"] = list_url
+                preview["listStatus"] = "fresh" if list_url else "unavailable" if preview["status"] == "fresh" else "not-run"
+                _PREVIEW_EVIDENCE[fn] = preview
                 browser_entries[fn] = {"formName": title, "previewUrl": url, "listUrl": list_url}
                 if api:
                     card["api"] = api
@@ -489,11 +518,14 @@ def render(
             )
 
     archive["artifacts"] = artifacts
+    previous_evidence = archive.get("previewEvidence")
+    archive["previewEvidence"] = {**{key: value for key, value in (previous_evidence.items() if isinstance(previous_evidence, dict) else [])
+                                   if key not in {number for number, _title in form_entries}}, **_PREVIEW_EVIDENCE}
     _write_json(archive_path, archive)
 
     if requested_numbers and set(deleted_numbers) == set(requested_numbers):
         raise DeletedArtifactNoCard(
-            "DELIVERY_NOT_APPLICABLE: requested forms were deleted; no artifact card was emitted"
+            "DELIVERY_NOT_APPLICABLE: every requested form was deleted; no artifact card was emitted"
         )
 
     if blocks and not wait_dym:
@@ -510,8 +542,9 @@ def render(
 
 
 def main() -> int:
-    global _TEST_ENVIRONMENT_HANDOFF
+    global _TEST_ENVIRONMENT_HANDOFF, _PREVIEW_EVIDENCE
     _TEST_ENVIRONMENT_HANDOFF = None
+    _PREVIEW_EVIDENCE = None
     parser = argparse.ArgumentParser(description="Render output cards")
     parser.add_argument("--app-root", required=True, help="App root directory")
     parser.add_argument("--wait-dym", action="store_true",
@@ -572,6 +605,8 @@ def main() -> int:
         print(block, flush=True)
     if _TEST_ENVIRONMENT_HANDOFF:
         print("TEST_ENVIRONMENT_HANDOFF=" + json.dumps(_TEST_ENVIRONMENT_HANDOFF, ensure_ascii=False), flush=True)
+    if _PREVIEW_EVIDENCE:
+        print("PREVIEW_EVIDENCE=" + json.dumps(_PREVIEW_EVIDENCE, ensure_ascii=False), flush=True)
     if _DYM_BACKGROUND_NOTICE:
         # 后台同步是必须交给宿主执行的动作，不是诊断日志。放在卡片块后的
         # stdout，避免调用方隐藏 stderr 时把同步请求一起丢弃。
@@ -580,9 +615,11 @@ def main() -> int:
     print(
         "DELIVERY: Preserve the exact blocks for the final delivery response; do not rerender them. "
         "These are domain artifacts, not evidence that the whole request or acceptance is complete. "
-        "For delegated implementation, return the blocks and actual results to the owner and continue "
-        "its remaining acceptance work. At whole-request finalization, call output_check once if "
-        "available, then include the blocks without Markdown links or code fences.",
+        "Formal Expert Team completion reuses the native cards saved in archive.json and publishes "
+        "them at the assigned range's successful endpoint; do not repeat host-published cards. "
+        "For other delegated implementation, return the blocks and actual results to the owner. "
+        "Standalone finalization calls output_check once if available, then includes the blocks "
+        "without Markdown links or code fences.",
         file=sys.stderr,
         flush=True,
     )