@shundoo-ai/dsh-cosmic 1.0.21 → 1.0.22

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

@@ -30,9 +30,10 @@ OWNERSHIP_ALIASES = {"patch-existing": "modify"}
 
 
 class HandoffError(ValueError):
-    def __init__(self, message: str, error_code: str = "PLUGIN_HANDOFF_UNRESOLVED") -> None:
+    def __init__(self, message: str, error_code: str = "PLUGIN_HANDOFF_UNRESOLVED", *, details: dict | None = None) -> None:
         super().__init__(message)
         self.error_code = error_code
+        self.details = details or {}
 
 
 def _read_json(path: str | Path) -> Any:
@@ -185,7 +186,8 @@ def _report_column_fields(artifact: dict) -> list[dict]:
     return result
 
 
-def _compile_report_contract(artifact: dict, form_number: str) -> dict | None:
+def _compile_report_contract(artifact: dict, form_number: str,
+                             filter_editors: dict | None = None) -> dict | None:
     """Compile the report plugin contract straight from the artifact.
 
     The report pipeline already writes this file, but a handoff must never depend on it: a
@@ -199,11 +201,33 @@ def _compile_report_contract(artifact: dict, form_number: str) -> dict | None:
         from _core.report_ops import compile_report_plugin_contract
     except ImportError:
         return None
-    return compile_report_plugin_contract(artifact, form_number)
+    return compile_report_plugin_contract(artifact, form_number, filter_editors=filter_editors)
+
+
+def _run_filter_editors(run_result: Any, form_number: str) -> dict | None:
+    """The filter editor outcome the report run recorded for this form, when it recorded one.
+
+    It says which editor each typed filter actually rendered — a platform without the typed
+    report filter patch renders the legacy control — so the plugin is told the value shape it
+    will really receive. The artifact alone can only say what was requested.
+    """
+    candidates = []
+    if isinstance(run_result, dict):
+        candidates.append(run_result.get("reportFilterEditors"))
+        for item in run_result.get("results") or []:
+            if isinstance(item, dict) and isinstance(item.get("result"), dict):
+                candidates.append(item["result"].get("reportFilterEditors"))
+    for editors in candidates:
+        if not isinstance(editors, dict):
+            continue
+        if str(editors.get("formNumber") or "") in ("", str(form_number or "")):
+            return editors
+    return None
 
 
 def _report_plugin_contract(
     report_artifacts: list[tuple[str, dict]], form_number: str,
+    filter_editors: dict | None = None,
 ) -> dict | None:
     """The requirements this report's plugin must implement, or None when it has none.
 
@@ -214,7 +238,7 @@ def _report_plugin_contract(
     was handed a contract missing whatever that generation could not yet express.
     """
     for artifact_path, artifact in report_artifacts:
-        contract = _compile_report_contract(artifact, form_number)
+        contract = _compile_report_contract(artifact, form_number, filter_editors)
         if contract:
             contract["source"] = f"compiled from {Path(artifact_path).name}"
             return contract
@@ -222,17 +246,41 @@ def _report_plugin_contract(
 
 
 def _registered_plugin_classes(artifact: dict) -> list[str]:
-    """Plugin FQCNs the artifact already registered on the platform."""
-    classes = []
+    """Plugin FQCNs the artifact already registered on the platform.
+
+    Both report plugin slots count: reportPlugins (the report list's data-fetch plugin) and
+    reportProperties.tree.ReportPlugin (the left tree's own data plugin). Reading only the first
+    made a left-tree report's tree class unpreparable: the list plugin was registered, so a
+    className naming the tree class failed with PLUGIN_CLASS_NOT_REGISTERED.
+    """
+    return [slot["className"] for slot in _registered_plugin_slots(artifact)]
+
+
+def _registered_plugin_slots(artifact: dict) -> list[dict]:
+    """Each registered plugin class with the plugin type its slot runs.
+
+    The type is what keeps one slot's classes from deciding another type's handoff. A report's
+    own reportform plugin sits in neither slot, so matching it against the slot classes either
+    refused its className with PLUGIN_CLASS_NOT_REGISTERED or, with no className given, handed
+    the coding step the data plugin's class and package.
+    """
+    slots: list[dict] = []
+    seen: set[str] = set()
     for plugin in artifact.get("reportPlugins") or []:
         if not isinstance(plugin, dict):
             continue
         if str(plugin.get("type") or "Java").strip().lower() != "java":
             continue
         class_name = str(plugin.get("className") or "").strip()
-        if class_name and class_name not in classes:
-            classes.append(class_name)
-    return classes
+        if class_name and class_name not in seen:
+            seen.add(class_name)
+            slots.append({"className": class_name, "type": "reportlist"})
+    properties = artifact.get("reportProperties")
+    tree = properties.get("tree") if isinstance(properties, dict) else None
+    tree_plugin = str(tree.get("ReportPlugin") or "").strip() if isinstance(tree, dict) else ""
+    if tree_plugin and tree_plugin not in seen:
+        slots.append({"className": tree_plugin, "type": "reporttreelist"})
+    return slots
 
 
 def _catalog(
@@ -276,8 +324,8 @@ def _catalog(
             "artifact": str(Path(artifact_path).resolve()),
         }
         forms.append(form_row)
-        for class_name in _registered_plugin_classes(artifact):
-            registered_plugins.append({**form_row, "className": class_name})
+        for slot in _registered_plugin_slots(artifact):
+            registered_plugins.append({**form_row, **slot})
         template_fields = {
             str(item.get("entityKey") or "").strip(): item.get("fields") or []
             for item in artifact.get("templateFields") or []
@@ -460,7 +508,7 @@ def _field_java_type(field_type: str) -> str | None:
     if field_type.startswith("Mul"):
         return None
     # Match the exact time-only types: DateTimeField also contains "TimeField" as a suffix.
-    if field_type in ("TimeProp", "TimeField"):
+    if field_type in ("TimeProp", "TimeField", "IntegerProp", "IntegerField"):
         return "Integer"
     for marker, java_type in _FIELD_JAVA_TYPES:
         if marker.lower() in field_type.lower():
@@ -503,9 +551,13 @@ def _field_contract(row: dict) -> dict | None:
     java_type = _field_java_type(field_type)
     if java_type:
         contract["javaType"] = java_type
+    if field_type in ("IntegerProp", "IntegerField"):
+        contract["valueAccessor"] = f'getInt("{field_key}")'
+        contract["note"] = "getInt returns a primitive; inspect the raw value first when empty differs from zero."
     if field_type in ("TimeProp", "TimeField"):
         contract["valueAccessor"] = f'getInt("{field_key}")'
         contract["timeValueUnit"] = "seconds-after-midnight"
+        contract["note"] = 'Target 8.0 time-only runtime: a negative raw value (observed empty sentinel -1) is empty/invalid; null is also empty. Zero is valid midnight. Inspect the raw value before getInt coercion, normalize empty values, then apply business-hour or ordering rules.'
     reference = (bool(row.get("refEntity") or row.get("refIdProperty"))
                  if field_type.endswith("Prop") else _is_reference_field(field_type))
     if reference and not field_type.startswith("Mul"):
@@ -594,6 +646,11 @@ def _external_scope(catalog: list[dict], selector: str) -> list[dict]:
     ]
 
 
+def _external_contract_scope(catalog: list[dict], entry: dict) -> list[dict]:
+    return [row for row in _external_scope(catalog, str(entry.get("entity") or ""))
+            if not entry.get("formNumber") or row.get("formNumber") == entry["formNumber"]]
+
+
 def _external_field(scope: list[dict], selector: Any) -> tuple[dict, str, dict | None]:
     """Resolve one exact field key/name, optionally scoped to one nested entity."""
     if isinstance(selector, dict):
@@ -640,7 +697,7 @@ def _external_field(scope: list[dict], selector: Any) -> tuple[dict, str, dict |
     )
 
 
-def _verify_external_contracts(contracts: list, catalog: list[dict]) -> list:
+def _verify_external_contract_entries(contracts: list, catalog: list[dict]) -> list:
     """Prove every declared external entity and field, or fail closed.
 
     Returns the same list with each verified entry enriched by ``verifiedFields``, so the
@@ -648,7 +705,7 @@ def _verify_external_contracts(contracts: list, catalog: list[dict]) -> list:
     """
     missing = list(dict.fromkeys(str(entry["entity"]).strip() for entry in contracts
         if isinstance(entry, dict) and entry.get("entity")
-        and not _external_scope(catalog, str(entry["entity"]))))
+        and not _external_contract_scope(catalog, entry)))
     if missing:
         raise HandoffError(
             "external contract entities/forms are not verified: " + ", ".join(missing)
@@ -664,9 +721,18 @@ def _verify_external_contracts(contracts: list, catalog: list[dict]) -> list:
         if not entity_selector:
             verified.append(entry)
             continue
-        scope = _external_scope(catalog, entity_selector)
+        scope = _external_contract_scope(catalog, entry)
         selectors = _contract_field_selectors(entry)
-        resolved = [_external_field(scope, selector) for selector in selectors]
+        resolved, errors = [], []
+        for selector in selectors:
+            try:
+                resolved.append(_external_field(scope, selector))
+            except HandoffError as exc:
+                errors.append((selector, str(exc)))
+        if errors:
+            failed = json.dumps([selector for selector, _message in errors], ensure_ascii=False)
+            raise HandoffError(f"unverified field selectors ({len(errors)}): {failed}; {errors[0][1]}",
+                               "PLUGIN_EXTERNAL_CONTRACT_UNVERIFIED")
         entities = {row["entityKey"] for row, _key, _field in resolved}
         if not resolved and len(scope) != 1:
             raise HandoffError(
@@ -691,6 +757,24 @@ def _verify_external_contracts(contracts: list, catalog: list[dict]) -> list:
     return verified
 
 
+def _verify_external_contracts(contracts: list, catalog: list[dict]) -> list:
+    verified, errors = [], []
+    for entry in contracts:
+        try:
+            verified.extend(_verify_external_contract_entries([entry], catalog))
+        except HandoffError as exc:
+            selector = str(entry.get("entity") or "") if isinstance(entry, dict) else str(entry)
+            errors.append((selector, exc))
+    if errors:
+        details = [f"{selector}: {str(error)[:700]}"
+                   + (" [diagnostic text omitted]" if len(str(error)) > 700 else "")
+                   for selector, error in errors[:8]]
+        remaining = f"; {len(errors) - 8} additional failed contracts omitted" if len(errors) > 8 else ""
+        raise HandoffError(f"{len(errors)} external contract(s) failed verification: " + "; ".join(details) + remaining,
+                           errors[0][1].error_code)
+    return verified
+
+
 def _verified_field(field_key: str, field: dict | None, entity: dict | None = None) -> dict:
     """One field of an external contract, as the read-back proved it."""
     if field is None:
@@ -717,6 +801,7 @@ def _verified_field(field_key: str, field: dict | None, entity: dict | None = No
     if field_type in ("TimeProp", "TimeField"):
         result["valueAccessor"] = f'getInt("{field_key}")'
         result["timeValueUnit"] = "seconds-after-midnight"
+        result["note"] = 'Target 8.0 time-only runtime: a negative raw value (observed empty sentinel -1) is empty/invalid; null is also empty. Zero is valid midnight. Inspect the raw value before getInt coercion, normalize empty values, then apply business-hour or ordering rules.'
     return result
 
 
@@ -750,6 +835,24 @@ def _verified_operation_keys(value: Any) -> set[str]:
     return found
 
 
+def _validate_operation_result(value: Any, form_number: str, app_root: str, keys: list[str]) -> set[str]:
+    if value is None:
+        raise HandoffError("type=operation requires a listOperations read-back via --operations-file")
+    verified = _verified_operation_keys(value)
+    for data in (value, value.get("data") if isinstance(value, dict) else None):
+        if not isinstance(data, dict):
+            continue
+        if data.get("formNumber") and data["formNumber"] != form_number:
+            raise HandoffError("listOperations result belongs to another form")
+        if data.get("appRoot") and Path(data["appRoot"]).resolve() != Path(app_root).resolve():
+            raise HandoffError("listOperations result belongs to another application")
+    missing = [key for key in keys if key not in verified]
+    if missing:
+        raise HandoffError("operationKeys are absent from listOperations read-back: " + ", ".join(missing)
+                           + "; available operationKeys: " + ", ".join(sorted(verified)))
+    return verified
+
+
 def operation_contracts(value: Any, keys: list[str]) -> list[dict]:
     """Preserve actual operation parameters instead of guessing business state transitions."""
     if isinstance(value, list):
@@ -774,21 +877,54 @@ def read_platform(app_root: str, command: str, selector: str, flag: str = "--for
     try:
         completed = subprocess.run([sys.executable, str(COSMIC_API), "--output", str(destination), command,
             "--app-root", str(Path(app_root).resolve()), flag, selector],
-            capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=60)
+            capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=240)
     except (OSError, subprocess.TimeoutExpired) as exc:
         raise HandoffError(f"{command} could not complete for {selector}", "PLUGIN_EVIDENCE_READ_FAILED") from exc
     if completed.returncode or not destination.is_file():
-        raise HandoffError(f"{command} failed for {selector}; no fresh evidence saved",
+        # 只保留结构化诊断，避免把子进程中的认证配置或完整元数据复制进错误串。
+        detail = {}
+        response = None
+        try:
+            response = json.loads(completed.stdout)
+            if isinstance(response, dict):
+                detail = {key: response[key] for key in ("errorCode", "phase", "retryable") if key in response}
+        except (ValueError, TypeError):
+            pass
+        response = _read_json(destination) if destination.is_file() else response
+        _raise_missing_entity(command, selector, response)
+        raise HandoffError(f"{command} failed for {selector}; no fresh evidence saved. "
+                           f"Child exit={completed.returncode}, diagnostics={json.dumps(detail)}. "
+                           "For unchanged external contracts, pass their exact successful getFormSchema files "
+                           "with --external-schema; never replace a failed current read with an implicit stale cache.",
                            "PLUGIN_EVIDENCE_READ_FAILED")
     value = _read_json(destination)
     if isinstance(value, dict) and (value.get("status") is False
             or value.get("errorCode") not in (None, "", 0, "0")
             or isinstance(value.get("data"), dict) and value["data"].get("success") is False):
+        _raise_missing_entity(command, selector, value)
         raise HandoffError(f"{command} failed for {selector}: {value.get('message') or value.get('errorCode')}",
                            "PLUGIN_EVIDENCE_READ_FAILED")
+    if command == "getEntityType" and isinstance(value, dict):
+        value = {**value, "_pluginEvidence": {"formNumber": selector, "path": str(destination),
+            "sha256": hashlib.sha256(destination.read_bytes()).hexdigest()}}
     return value
 
 
+def _raise_missing_entity(command: str, selector: str, response: Any) -> None:
+    """Only a structured entity-metadata miss permits the related-form schema fallback."""
+    if command != "getEntityType" or not isinstance(response, dict):
+        return
+    layers = [response, response.get("data")]
+    for layer in layers:
+        if not isinstance(layer, dict):
+            continue
+        message = str(layer.get("message") or "").strip()
+        if (re.fullmatch(r"实体.+?元数据不存在[。.!！]?", message)
+                or layer.get("errorCode") in {"bos.entityMetaDataNotExist", "ENTITY_METADATA_NOT_FOUND", "METADATA_NOT_FOUND"}):
+            raise HandoffError(f"getEntityType metadata does not exist for {selector}",
+                               "PLUGIN_ENTITY_METADATA_NOT_FOUND")
+
+
 def prepare_inputs(*, app_root: str, intent: dict, plugin_type: str, artifact_paths: list[str],
                    run_result: Any, operation_result: Any, external_schemas: list[Any]) -> tuple[Any, list[Any]]:
     """Collect only missing read-only platform evidence for this verified target."""
@@ -814,7 +950,7 @@ def prepare_inputs(*, app_root: str, intent: dict, plugin_type: str, artifact_pa
     missing = [entry for name in ("externalContracts", "externalApis")
         for entry in _contract_list(specialized.get(name), name)
         if isinstance(entry, dict) and entry.get("entity")
-        and not _external_scope(catalog, str(entry["entity"]))]
+        and not _external_contract_scope(catalog, entry)]
     selectors = list(dict.fromkeys(str(entry.get("formNumber") or entry["entity"]) for entry in missing))
     invalid = [selector for selector in selectors if not re.fullmatch(r"[A-Za-z0-9_]+", selector)]
     if invalid:
@@ -894,8 +1030,9 @@ def runtime_catalog(snapshots: list[Any]) -> tuple[list[dict], list[dict], list[
     return forms, entities, fields, []
 
 
-def prepare_runtime_inputs(app_root: str, form_number: str, intent: dict, plugin_type: str) -> tuple[list[Any], Any]:
-    """Read current main/explicitly referenced forms once, independently of modeling artifacts."""
+def prepare_runtime_inputs(app_root: str, form_number: str, intent: dict, plugin_type: str,
+                           *, operation_result: Any = None, external_schemas: list[Any] | None = None) -> tuple[list[Any], Any]:
+    """Read the main graph once; reuse explicit evidence and parallelize independent reads."""
     _string_list(intent.get("coreLogic"), "coreLogic", required=True)
     keys = _string_list(intent.get("operationKeys"), "operationKeys")
     if plugin_type == "operation" and not keys:
@@ -907,36 +1044,60 @@ def prepare_runtime_inputs(app_root: str, form_number: str, intent: dict, plugin
         raise HandoffError("declare specialized.unresolvedDependencies before platform reads")
     if specialized["unresolvedDependencies"]:
         raise HandoffError("resolve declared dependencies before platform reads", "PLUGIN_EXTERNAL_CONTRACT_UNRESOLVED")
-    main = read_platform(app_root, "getEntityType", form_number, "--entityId")
+    schemas = external_schemas if external_schemas is not None else []
+    external_catalog = _external_entity_catalog(schemas)
+    from concurrent.futures import ThreadPoolExecutor
+    with ThreadPoolExecutor(max_workers=2) as pool:
+        main_read = pool.submit(read_platform, app_root, "getEntityType", form_number, "--entityId")
+        operation_read = (pool.submit(read_platform, app_root, "listOperations", form_number)
+                          if plugin_type == "operation" and operation_result is None else None)
+        main = main_read.result()
+        if operation_read is not None:
+            operation_result = operation_read.result()
     forms, entities, fields, _ = runtime_catalog([main])
     if forms[0]["formNumber"] != form_number:
         raise HandoffError("runtime metadata belongs to another form", "PLUGIN_CONTEXT_INCOMPLETE")
-    archive = Path(app_root) / "archive.json"
-    identity = _read_json(archive) if archive.is_file() else {}
-    if forms[0].get("appCode") and identity.get("appCode") and forms[0]["appCode"] != identity["appCode"]:
-        raise HandoffError("runtime main form belongs to another application", "PLUGIN_CONTEXT_INCOMPLETE")
+    if plugin_type == "operation":
+        _validate_operation_result(operation_result, form_number, app_root, keys)
     references = {field["refEntity"] for field in fields if field.get("refEntity")}
     requests = []
-    catalog = _artifact_external_catalog(entities, fields)
+    catalog = _artifact_external_catalog(entities, fields) + external_catalog
     for name in ("externalContracts", "externalApis"):
         for entry in _contract_list(specialized.get(name), name):
-            if not isinstance(entry, dict) or not entry.get("entity") or _external_scope(catalog, str(entry["entity"])):
+            if not isinstance(entry, dict) or not entry.get("entity") or _external_contract_scope(catalog, entry):
                 continue
             selector = str(entry.get("formNumber") or entry["entity"])
             if not re.fullmatch(r"[A-Za-z0-9_]+", selector):
-                # Resolve a unique declared reference's display name from its native metadata.
-                # Fetching declared reference targets is bounded to this form, never a global form tour.
+                # Only the main form's declared references may resolve an exact display name.
                 requests += sorted(references)
             else:
                 requests.append(selector)
-    from concurrent.futures import ThreadPoolExecutor
+
+    def related_read(selector: str) -> tuple[Any, Any]:
+        try:
+            native = read_platform(app_root, "getEntityType", selector, "--entityId")
+        except HandoffError as exc:
+            if exc.error_code != "PLUGIN_ENTITY_METADATA_NOT_FOUND":
+                raise
+            schema = read_platform(app_root, "getFormSchema", selector)
+            related_catalog = _external_entity_catalog([schema])
+            if not related_catalog or any(row["formNumber"] != selector for row in related_catalog):
+                raise HandoffError("related schema belongs to another form", "PLUGIN_EXTERNAL_CONTRACT_UNVERIFIED")
+            return None, schema
+        related_forms, _, _, _ = runtime_catalog([native])
+        if related_forms[0]["formNumber"] != selector:
+            raise HandoffError("related runtime metadata belongs to another form", "PLUGIN_CONTEXT_INCOMPLETE")
+        return native, None
+
     with ThreadPoolExecutor(max_workers=4) as pool:
-        related = list(pool.map(lambda selector: read_platform(app_root, "getEntityType", selector, "--entityId"),
-                               dict.fromkeys(requests)))
-    snapshots = [main] + related
-    runtime_catalog(snapshots)  # Fail before coding when any requested graph is incomplete.
-    operations = read_platform(app_root, "listOperations", form_number) if plugin_type == "operation" else None
-    return snapshots, operations
+        related = list(pool.map(related_read, dict.fromkeys(requests)))
+    snapshots = [main] + [native for native, _schema in related if native is not None]
+    schemas.extend(schema for _native, schema in related if schema is not None)
+    _, related_entities, related_fields, _ = runtime_catalog(snapshots)
+    catalog = _artifact_external_catalog(related_entities, related_fields) + _external_entity_catalog(schemas)
+    for name in ("externalContracts", "externalApis"):
+        _verify_external_contracts(_contract_list(specialized.get(name), name), catalog)
+    return snapshots, operation_result
 
 
 def _bind_unique_mentions(
@@ -986,20 +1147,106 @@ def _conventional_class_name(form_number: str, class_suffix: str | None) -> str
     return "".join(part[:1].upper() + part[1:] for part in parts) + class_suffix
 
 
+def read_ui_context(app_root: str, form_number: str, plugin_type: str, *, include_list: bool = False) -> dict:
+    """Read and validate the selected page without requiring a runtime entity."""
+    import xml.etree.ElementTree as ET
+    response = read_platform(app_root, "getFormMetadata", form_number, "--formId")
+    data = response.get("data") if isinstance(response, dict) else None
+    xml = data if isinstance(data, str) else (data.get("xml") or data.get("metadata") or data.get("formMetadata")) if isinstance(data, dict) else None
+    if not isinstance(xml, str) or not xml.strip():
+        raise HandoffError("page metadata did not contain XML", "PLUGIN_CONTEXT_INCOMPLETE")
+    try:
+        root = ET.fromstring(xml)
+    except ET.ParseError as exc:
+        raise HandoffError("page metadata XML is invalid", "PLUGIN_CONTEXT_INCOMPLETE") from exc
+    from run import _xml_child_text, _xml_localname, parse_form_metadata_xml_document
+    if _xml_localname(root.tag) != "FormMetadata":
+        root = next((item for item in root.iter() if _xml_localname(item.tag) == "FormMetadata"), None)
+    items = next((item for item in root if _xml_localname(item.tag) == "Items"), None) if root is not None else None
+    if root is None or _xml_child_text(root, "Key") != form_number or items is None:
+        raise HandoffError("page metadata does not prove the selected form identity and layout", "PLUGIN_CONTEXT_INCOMPLETE")
+    form_config, control_tree, list_config, list_meta = parse_form_metadata_xml_document(xml)
+    if form_config is None and control_tree is None:
+        raise HandoffError("page layout is absent", "PLUGIN_CONTEXT_INCOMPLETE")
+    if include_list and (not isinstance(list_config, dict) or not isinstance(list_meta, dict)):
+        raise HandoffError("list metadata is absent", "PLUGIN_CONTEXT_INCOMPLETE")
+    controls = []
+    def visit(node):
+        if isinstance(node, dict):
+            if node.get("Key") and node.get("_Type_"):
+                controls.append({"key": node["Key"], "type": node["_Type_"]})
+            for child in node.values():
+                if isinstance(child, (dict, list)):
+                    visit(child)
+        elif isinstance(node, list):
+            for child in node:
+                visit(child)
+    visit(control_tree)
+    # A control key is not necessarily a model field. Only expose an explicit
+    # page-field binding from the returned XML; never derive a field from the key.
+    bindings = {}
+    for item in root.iter():
+        key = _xml_child_text(item, "Key")
+        field = _xml_child_text(item, "FieldKey") or _xml_child_text(item, "FieldName")
+        if key and field:
+            bindings.setdefault(key, set()).add(field)
+    for control in controls:
+        matches = bindings.get(control["key"], set())
+        if len(matches) == 1:
+            control["fieldKey"] = next(iter(matches))
+    if include_list:
+        tree = list_meta.get("BillList")
+        visit(json.loads(tree) if isinstance(tree, str) else tree)
+    list_plugin = plugin_type in {"listform", "treelist", "moblist"}
+    plugin_rows = ((list_config or {}).get("plugins", []) if list_plugin else (form_config or {}).get("Plugins", []))
+    if not list_plugin and not plugin_rows:
+        from run import _kingdee_plugins_from_basedata
+        for host in items:
+            if _xml_localname(host.tag) in {"FormAp", "BillFormAp", "BasedataFormAp"}:
+                plugin_rows.extend(_kingdee_plugins_from_basedata(host)[0])
+    plugins = [{"className": item.get("ClassName") or item.get("className"), "type": "form" if plugin_type == "operation" else plugin_type}
+               for item in plugin_rows if isinstance(item, dict)
+               and (item.get("ClassName") or item.get("className")) and item.get("Enabled", item.get("enabled", True))]
+    return {"formNumber": form_number, "formName": _xml_child_text(root, "Name") or form_number,
+            "modelType": _xml_child_text(root, "ModelType") or None, "controls": controls, "plugins": plugins,
+            "source": "getFormMetadata"}
+
+
 def prepare_handoff(
     *, app_root: str, project_root: str | None, plugin_type: str,
     intent: dict, artifact_paths: list[str], run_result: Any = None,
     operation_result: Any = None, external_schemas: list[Any] | None = None,
-    runtime_metadata: list[Any] | None = None,
+    runtime_metadata: list[Any] | None = None, ui_context: dict | None = None, operation_context: dict | None = None, source_only: bool = False, prepare_source: bool = False, refresh_report_state: bool = False,
 ) -> dict:
     if not isinstance(intent, dict):
         raise HandoffError("intent must be a JSON object")
+    if refresh_report_state and (not artifact_paths or runtime_metadata is not None):
+        raise HandoffError("--refresh-report-state requires a complete report artifact, not runtime metadata", "PLUGIN_REPORT_STATE_INPUT_INVALID")
     if runtime_metadata is not None:
         if not runtime_metadata:
             raise HandoffError("runtime metadata is empty", "PLUGIN_CONTEXT_INCOMPLETE")
         artifact_paths = []
     forms, entities, fields, registered_plugins = (runtime_catalog(runtime_metadata) if runtime_metadata
         else _catalog(artifact_paths, run_result))
+    if operation_context:
+        if not forms:
+            forms = [{"formNumber": operation_context["formNumber"], "formName": operation_context["formNumber"]}]
+        elif not any(row["formNumber"] == operation_context["formNumber"] for row in forms):
+            raise HandoffError("operation and entity metadata identify different forms", "PLUGIN_CONTEXT_INCOMPLETE")
+    if source_only:
+        if plugin_type == "operation" or intent.get("ownershipMode") != "modify" or not intent.get("sourcePath"):
+            raise HandoffError("source-only preparation requires an existing non-operation class", "PLUGIN_CONTEXT_INCOMPLETE")
+        forms = [{"formNumber": "", "formName": ""}]
+    if ui_context:
+        if forms and not any(row["formNumber"] == ui_context["formNumber"] for row in forms):
+            raise HandoffError("page and entity metadata identify different forms", "PLUGIN_CONTEXT_INCOMPLETE")
+        if not forms:
+            forms = [{"formNumber": ui_context["formNumber"], "formName": ui_context["formName"]}]
+        registered_plugins += [{"formNumber": ui_context["formNumber"], **item} for item in ui_context["plugins"]]
+        if not runtime_metadata:
+            fields += [{"formNumber": ui_context["formNumber"], "formName": ui_context["formName"],
+                        "fieldKey": control["fieldKey"], "fieldName": control["fieldKey"], "role": "header"}
+                       for control in ui_context["controls"] if control.get("fieldKey")]
     main_form = _exact_one(forms, intent.get("form"), ("formName", "formNumber"), "form")
     related = None
     if intent.get("relatedForm"):
@@ -1009,24 +1256,8 @@ def prepare_handoff(
     operation_keys = _string_list(intent.get("operationKeys"), "operationKeys")
     if plugin_type == "operation" and not operation_keys:
         raise HandoffError("type=operation requires operationKeys")
-    if plugin_type == "operation":
-        if operation_result is None:
-            raise HandoffError("type=operation requires a listOperations read-back via --operations-file")
-        verified_operations = _verified_operation_keys(operation_result)
-        operation_data = operation_result.get("data") if isinstance(operation_result, dict) else None
-        if isinstance(operation_data, dict):
-            if operation_data.get("formNumber") and operation_data["formNumber"] != main_form["formNumber"]:
-                raise HandoffError("listOperations result belongs to another form")
-            if operation_data.get("appRoot") and Path(operation_data["appRoot"]).resolve() != Path(app_root).resolve():
-                raise HandoffError("listOperations result belongs to another application")
-        missing_operations = [key for key in operation_keys if key not in verified_operations]
-        if missing_operations:
-            raise HandoffError(
-                "operationKeys are absent from listOperations read-back: "
-                + ", ".join(missing_operations)
-            )
-    else:
-        verified_operations = set()
+    verified_operations = (_validate_operation_result(operation_result, main_form["formNumber"], app_root, operation_keys)
+                           if plugin_type == "operation" else set())
     if plugin_type != "operation" and operation_keys:
         raise HandoffError("operationKeys are only valid for type=operation")
     trigger = str(intent.get("trigger") or "").strip()
@@ -1039,7 +1270,24 @@ def prepare_handoff(
             "ownershipMode must be create-new or modify (patch-existing is accepted as modify)"
         )
 
-    path_result = resolve_output_path(app_root, plugin_type, project_root)
+    source_directory = intent.get("sourceDirectory")
+    if source_directory is not None and (not isinstance(source_directory, str) or not Path(source_directory).is_absolute()):
+        raise HandoffError("sourceDirectory must be an absolute Java package directory", "PLUGIN_WORKSPACE_UNRESOLVED")
+    explicit_source = intent.get("sourcePath") if ownership_mode == "modify" else None
+    if explicit_source and not Path(explicit_source).expanduser().is_absolute():
+        raise HandoffError("sourcePath must be absolute", "PLUGIN_WORKSPACE_UNRESOLVED")
+    source_resolution = source_directory
+    if (source_directory or explicit_source) and not project_root:
+        directory = Path(source_directory).expanduser().resolve() if source_directory else Path(explicit_source).expanduser().resolve().parent
+        source_resolution = str(directory)
+        java_root = next((item for item in (directory, *directory.parents)
+                          if item.name == "java" and item.parent.name == "main" and item.parent.parent.name == "src"), None)
+        if java_root is None:
+            raise HandoffError("sourceDirectory must be inside a Java module src/main/java", "PLUGIN_WORKSPACE_UNRESOLVED")
+        project_root = str(java_root.parent.parent.parent)
+    path_result = resolve_output_path(app_root, plugin_type, project_root,
+                                      prepare_source=prepare_source and ownership_mode == "create-new",
+                                      source_directory=source_resolution)
     if not path_result.get("projectRoot"):
         raise HandoffError(
             path_result.get("error") or "cannot determine the Java project root",
@@ -1054,11 +1302,20 @@ def prepare_handoff(
     # The appCode-derived convention package would silently disagree with it and the class
     # would not be found at runtime, so the registered FQCN wins here.
     package_path = path_result.get("packagePath")
-    package_source = "appCode convention" if package_path else None
+    package_source = ("selected source directory" if source_directory else "appCode convention") if package_path else None
     form_plugins = [
         row for row in registered_plugins
         if row["formNumber"] == main_form["formNumber"]
+        # A registered row names the slot its class runs in; a plugin of another type, such as
+        # the report form's own reportform plugin, is none of them. `report-plugin` is the
+        # registry's older name for the data-fetch type and runs in the same slot.
+        and row.get("type", plugin_type) == ("reportlist" if plugin_type == "report-plugin" else plugin_type)
     ]
+    # A page can have several independent plugins. Creating a new class must not
+    # reuse an unrelated registered class, while an existing identity stays protected.
+    page_plugins = form_plugins if ui_context and ownership_mode == "create-new" else []
+    if page_plugins:
+        form_plugins = []
     if form_plugins:
         if class_name:
             matching = [row for row in form_plugins if row["className"].rsplit(".", 1)[-1] == class_name]
@@ -1090,11 +1347,13 @@ def prepare_handoff(
                 f"registered plugin class {registered_class!r} must match [A-Za-z][A-Za-z0-9]*",
                 "PLUGIN_CLASS_NOT_QUALIFIED",
             )
+        if source_directory and registered_package.replace(".", "/") != package_path:
+            raise HandoffError("registered class package differs from the selected source directory", "PLUGIN_CLASS_NOT_REGISTERED")
         package_path = registered_package.replace(".", "/")
         package_source = "registered plugin className"
         class_name = registered_class
 
-    if not package_path:
+    if not package_path and ownership_mode != "modify":
         raise HandoffError(
             path_result.get("error") or "cannot determine packagePath",
             str(path_result.get("errorCode") or "PLUGIN_PACKAGE_UNRESOLVED"),
@@ -1131,6 +1390,9 @@ def prepare_handoff(
                 raise HandoffError("existing source package conflicts with the registered plugin class", "PLUGIN_CLASS_NOT_REGISTERED")
             package_path = source_package
             package_source = "existing source declaration"
+        elif not package_path:
+            package_path = ""
+            package_source = "existing source default package"
     else:
         # An existing file at the create-new target means the class is already in this project,
         # so generating it again would either duplicate its methods or overwrite its logic. The
@@ -1138,6 +1400,8 @@ def prepare_handoff(
         # the case where the caller never checked whether the class was already there.
         candidate = class_name or _conventional_class_name(
             main_form["formNumber"], path_result.get("classSuffix"))
+        if candidate and any(row["className"].rsplit(".", 1)[-1] == candidate for row in page_plugins):
+            raise HandoffError(f"class {candidate} is already registered; use ownershipMode=modify", "PLUGIN_OWNERSHIP_CONFLICT")
         target = (
             Path(path_result["projectRoot"]) / "src" / "main" / "java" / package_path / f"{candidate}.java"
             if candidate else None
@@ -1234,11 +1498,27 @@ def prepare_handoff(
         "fields": field_map,
         "coreLogic": core_logic,
         "specialized": specialized,
+        "sdkUsage": intent.get("sdkUsage", []),
+        **({"metadataNeeds": intent["metadataNeeds"]} if "metadataNeeds" in intent else {}),
         "description": (str(intent.get("description") or "").strip() or core_logic[0])[:20],
     }
+    if ui_context:
+        handoff["uiContext"] = ui_context
+    evidence_files = [snapshot["_pluginEvidence"] for snapshot in runtime_metadata or []
+                      if isinstance(snapshot, dict) and isinstance(snapshot.get("_pluginEvidence"), dict)]
+    if evidence_files:
+        handoff["entityEvidence"] = evidence_files
+    binding = Path(app_root).resolve() / "_runtime" / "context.json"
+    if (ui_context or evidence_files) and binding.is_file():
+        import hashlib
+        handoff["reuseBinding"] = {"path": str(binding), "sha256": hashlib.sha256(binding.read_bytes()).hexdigest()}
+    if operation_context:
+        handoff["operationContext"] = operation_context
+    if source_only:
+        handoff["sourceContext"] = {"scope": "source-only", "sourcePath": str(Path(source_path).expanduser().resolve())}
     if runtime_metadata:
         def graph(form: dict) -> dict:
-            return {key: form[key] for key in ("formNumber", "formName", "metadataSource", "metadataVersion")} | {
+            return {key: form[key] for key in ("formNumber", "formName", "metadataSource", "metadataVersion", "appCode")} | {
                 "entities": [{key: entity[key] for key in
                     ("entityKey", "entityName", "entityType", "role", "parentEntityKey", "collectionProperty", "collectionPath")}
                     | {"fields": [_field_contract(row) for row in fields
@@ -1248,6 +1528,9 @@ def prepare_handoff(
         handoff["relatedForms"] = [graph(form) for form in forms if form["formNumber"] != main_form["formNumber"]]
         handoff["entities"].update({row["entityName"]: row["entityKey"] for row in entities
                                    if row["formNumber"] == main_form["formNumber"]})
+    if operation_result is not None and plugin_type != "operation":
+        verified = _validate_operation_result(operation_result, main_form["formNumber"], app_root, [])
+        handoff["availableOperations"] = operation_contracts(operation_result, sorted(verified))
     if operation_keys:
         handoff["operationContracts"] = operation_contracts(operation_result, operation_keys)
         if runtime_metadata:
@@ -1290,10 +1573,38 @@ def prepare_handoff(
     report_artifacts = [
         (path, artifact)
         for path, artifact in ((path, _read_json(path)) for path in artifact_paths)
-        if isinstance(artifact, dict)
+        if isinstance(artifact, dict) and str(Path(path).resolve()) == main_form.get("artifact")
         and _is_report_entity((artifact.get("entities") or [None])[0])
     ]
-    report_contract = _report_plugin_contract(report_artifacts, main_form["formNumber"])
+    report_state_path = Path(app_root).resolve() / "_runtime" / f"{main_form['formNumber']}.report-authoring.json"
+    filter_editors = _run_filter_editors(run_result, main_form["formNumber"])
+    if refresh_report_state and not report_artifacts:
+        raise HandoffError("--refresh-report-state requires the selected form's complete report artifact", "PLUGIN_REPORT_STATE_INPUT_INVALID")
+    state_inputs = []
+    if report_artifacts and (report_state_path.is_file() or refresh_report_state):
+        _compile_report_contract(report_artifacts[0][1], main_form["formNumber"])
+        from _core.report_ops import report_readback_verification, write_report_authoring_state
+        if refresh_report_state:
+            schema = read_platform(app_root, "getReportSchema", main_form["formNumber"])
+            artifact = report_artifacts[0][1]
+            checks = [report_readback_verification(section, artifact.get(key) or [], schema)
+                      for section, key in (("columns", "reportColumns"), ("filters", "reportFilters"))]
+            if (schema.get("formNumber") != main_form["formNumber"] or not schema.get("formId")
+                or (main_form.get("formId") and main_form["formId"] != schema["formId"])
+                or any(not item.get("verified") for item in checks)):
+                raise HandoffError("Full report artifact must match current observable metadata before local reconciliation", "PLUGIN_REPORT_STATE_MISMATCH")
+            # 旧运行回执的 editorStatus 不属于本次独立读取，不复制为当前证据。
+            write_report_authoring_state(app_root, main_form["formNumber"], schema["formId"], artifact, schema)
+        import hashlib
+        state_inputs = [{"path": str(report_state_path), "sha256": hashlib.sha256(report_state_path.read_bytes()).hexdigest()}]
+        state = _read_json(report_state_path)
+        if (not isinstance(state, dict) or state.get("status") != "current" or state.get("formNumber") != main_form["formNumber"]
+            or not state.get("formId") or (main_form.get("formId") and state["formId"] != main_form["formId"])):
+            raise HandoffError("Report authoring state is incomplete; reconcile the full current artifact with --refresh-report-state (read-only platform lookup)", "PLUGIN_REPORT_STATE_STALE")
+        if _compile_report_contract(state.get("artifact"), main_form["formNumber"]) != _compile_report_contract(report_artifacts[0][1], main_form["formNumber"]):
+            raise HandoffError(f"Supplied report artifact is stale; use current artifactPath {state.get('artifactPath')} or reconcile a complete artifact with --refresh-report-state", "PLUGIN_REPORT_STATE_STALE")
+        filter_editors = state.get("filterEditors")
+    report_contract = _report_plugin_contract(report_artifacts, main_form["formNumber"], filter_editors)
     if report_contract:
         # Column types, presentation binding and non-persisted filter requirements are part of
         # the plugin's job, not optional polish, so they travel inside the handoff itself.
@@ -1305,9 +1616,9 @@ def prepare_handoff(
     if source_path:
         handoff["sourcePath"] = str(Path(source_path).expanduser().resolve())
     if class_name:
-        handoff["fqcn"] = package_path.replace("/", ".") + "." + class_name
+        handoff["fqcn"] = ".".join(part for part in (package_path.replace("/", "."), class_name) if part)
     try:
-        handoff["codingEvidence"] = plugin_coding_evidence(plugin_type, _string_list(intent.get("scenes"), "scenes"))
+        handoff["codingEvidence"] = plugin_coding_evidence(plugin_type, _string_list(intent.get("scenes"), "scenes"), core_logic=core_logic, hit_modules=specialized["hitModules"])
     except ValueError as exc:
         raise HandoffError(str(exc), "PLUGIN_CODING_EVIDENCE_INVALID") from exc
     if ownership_mode == "modify":
@@ -1315,8 +1626,11 @@ def prepare_handoff(
         # list means an empty class body rather than an unread file. New logic belongs inside
         # these; declaring one of them again is rejected by the compile boundary.
         handoff["existingMethods"] = existing_methods
+    state_inputs.extend({"path": row["path"], "sha256": row["sha256"]} for row in evidence_files)
     return {
         "status": True,
+        "inputFiles": state_inputs,
+        **({"reportStatePath": str(report_state_path)} if report_artifacts and report_state_path.is_file() else {}),
         "handoff": handoff,
         "evidence": {
             "forms": [{"formName": row["formName"], "formNumber": row["formNumber"]} for row in forms],
@@ -1337,15 +1651,20 @@ def prepare_handoff(
 
 def handoff_response(result: dict, *, full_output: bool = False) -> dict:
     """Keep the CLI below the host output limit; the saved context remains complete."""
+    coding_start = [sys.executable, str(Path(__file__).with_name("query_plugin_handoff.py")), "coding-start", "--handoff", result["handoffPath"]]
     if full_output:
-        return {key: result[key] for key in ("status", "handoffPath", "handoff")}
+        return {**{key: result[key] for key in ("status", "handoffPath", "handoff", "sourcePreparation") if key in result},
+                "codingStartCommand": coding_start}
     handoff = result["handoff"]
     coding = handoff.get("codingEvidence", {})
     graphs = [handoff["formGraph"], *handoff.get("relatedForms", [])] if handoff.get("formGraph") else []
+    page = handoff.get("uiContext") if not graphs else None
     return {
         "status": result["status"],
         "handoffPath": result["handoffPath"],
+        "codingStartCommand": coding_start,
         "contextMode": "reference-only",
+        **({"sourcePreparation": result["sourcePreparation"]} if "sourcePreparation" in result else {}),
         "handoff": {
             **{key: handoff[key] for key in (
                 "appRoot", "projectRoot", "packagePath", "type", "ownershipMode", "formNumber",
@@ -1361,21 +1680,22 @@ def handoff_response(result: dict, *, full_output: bool = False) -> dict:
             },
         },
         "metadata": {
-            "formCount": len(graphs),
+            "formCount": len(graphs) + (1 if page else 0),
             "forms": [{
                 **{key: graph[key] for key in ("formNumber", "metadataSource", "metadataVersion") if key in graph},
                 "entityCount": len(graph.get("entities", [])),
                 "fieldCount": sum(len(entity.get("fields", [])) for entity in graph.get("entities", [])),
-            } for graph in graphs[:8]],
+            } for graph in graphs[:8]] + ([{"formNumber": page["formNumber"], "metadataSource": page["source"],
+                "controlCount": len(page.get("controls", []))}] if page else []),
         },
-        "contextSections": ["handoff.formGraph", "handoff.relatedForms", "handoff.specialized",
-                            "handoff.operationContracts", "handoff.stateFields", "handoff.stateWarnings",
-                            "handoff.codingEvidence", "handoff.reportContract", "handoff.targetSdk"],
+        "contextSections": ["handoff." + key for key in ("formGraph", "relatedForms", "uiContext", "sourceContext",
+                            "operationContext", "specialized", "operationContracts", "stateFields", "stateWarnings",
+                            "codingEvidence", "reportContract", "targetSdk") if key in handoff],
         "instruction": (
             "This response is a summary, not the coding context. Keep the complete saved handoffPath "
-            "for native compilation; begin with query_plugin_handoff.py coding-start, then query only missing field paths, collection hierarchy, external contracts, "
+            "for native compilation; execute codingStartCommand directly, then query only missing field paths, collection hierarchy, external contracts, "
             "operation values, warnings and SDK signatures needed for this class with query_plugin_handoff.py. "
-            "Index or find exact paths before get; do not read the whole JSON into the model. Use its exact codingEntry "
+            "Use known JSON pointers directly with get; use index or find only for unknown paths; do not read the whole JSON into the model. Use its exact codingEntry "
             "and verified signatureTypes imports; missing or ambiguous SDK types require the supplied API lookup. "
             "Pass handoffPath directly to compile_plugin_source.py --handoff; do not search for another file."
         ),
@@ -1388,12 +1708,13 @@ def assert_handoff_replace(destination: Path, result: dict, replace: bool = Fals
     existing = _read_json(destination)
     previous = existing.get("handoff") if isinstance(existing, dict) and existing.get("status") is True else None
     current = result["handoff"]
-    fields = ("projectRoot", "appRoot", "sourcePath", "fqcn", "formNumber", "type", "coreLogic")
+    fields = ("projectRoot", "appRoot", "sourcePath", "fqcn", "formNumber", "type", "coreLogic",
+              "ownershipMode", "fields", "fieldContracts", "specialized", "sdkUsage", "reportContract")
     if not isinstance(previous, dict) or any(previous.get(key) != current.get(key) for key in fields) or sorted(
             previous.get("operationKeys", [])) != sorted(current.get("operationKeys", [])):
         raise HandoffError(
             f"Prepared class already has a different snapshot at {destination}. "
-            "Review the existing snapshot and reconcile the class identity and business scope before explicitly replacing it with --replace-handoff.",
+            "For a separate plugin class, set an explicit intent.className. For the same class, reconcile its full business scope before explicitly replacing it with --replace-handoff.",
             "PLUGIN_HANDOFF_CONFLICT")
 
 
@@ -1407,6 +1728,7 @@ def main() -> None:
     artifacts.add_argument("--artifact", action="append", dest="artifact_paths")
     artifacts.add_argument("--emit-manifest", help="Exact manifest path returned by the emitter; includes every declared artifact")
     parser.add_argument("--run-result")
+    parser.add_argument("--refresh-report-state", action="store_true", help="Reconcile a complete report artifact against current getReportSchema; never writes platform metadata")
     parser.add_argument("--form-number", help="Exact existing form number; independently reads runtime metadata")
     parser.add_argument("--operations-file", help="Reuse an existing listOperations result; otherwise read once automatically")
     parser.add_argument("--output", help="Save prepared context here; default is the app-local class handoff file")
@@ -1421,41 +1743,99 @@ def main() -> None:
     intent_group.add_argument("--intent-file")
     args = parser.parse_args()
     try:
+        import hashlib
+        from query_plugin_handoff import validate_input_files
+        input_files = [{"path": str(Path(path).resolve()), "sha256": hashlib.sha256(Path(path).read_bytes()).hexdigest()}
+                       for path in dict.fromkeys(filter(None, [args.intent_file, args.run_result, args.operations_file,
+                           args.emit_manifest, *(args.external_schemas or [])]))]
         intent = json.loads(args.intent_json) if args.intent_json else _read_json(args.intent_file)
         if not isinstance(intent, dict):
             raise HandoffError("intent must be a JSON object")
+        if not args.project_root and not intent.get("sourceDirectory") and not (intent.get("ownershipMode") == "modify" and intent.get("sourcePath")):
+            raise HandoffError("Java plugin directory is not specified; ask the user for the source directory before continuing", "PLUGIN_WORKSPACE_UNRESOLVED")
         run_result = _read_json(args.run_result) if args.run_result else None
         if run_result is not None and not isinstance(run_result, dict):
             raise HandoffError("write result must be a JSON object")
         operation_result = _read_json(args.operations_file) if args.operations_file else None
+        external_schemas = [_read_json(path) for path in args.external_schemas or []]
         artifact_paths = (manifest_artifacts(args.emit_manifest) if args.emit_manifest else args.artifact_paths
                           or (run_result or {}).get("artifactPaths"))
+        if args.plugin_type != "operation" and (not args.form_number or args.plugin_type in {"reportlist", "report-plugin", "reportform", "reporttreelist"}):
+            input_files.extend({"path": str(Path(path).resolve()), "sha256": hashlib.sha256(Path(path).read_bytes()).hexdigest()}
+                               for path in artifact_paths or [])
         runtime_metadata = None
-        if args.form_number or not artifact_paths or args.plugin_type == "operation":
+        ui_context = None
+        operation_context = None
+        needs = intent.get("metadataNeeds")
+        if needs is not None:
+            needs = _string_list(needs, "metadataNeeds")
+            if set(needs) - {"form", "list", "entity", "operate"}:
+                raise HandoffError("unknown metadataNeeds", "PLUGIN_CONTEXT_INCOMPLETE")
+            if args.plugin_type == "operation" and "operate" not in needs:
+                raise HandoffError("operation plugins require operation evidence", "PLUGIN_CONTEXT_INCOMPLETE")
+            if "entity" not in needs and ((intent.get("fields") and not ({"form", "list"} & set(needs))) or intent.get("entities") or intent.get("relatedForm")
+                    or (intent.get("specialized") or {}).get("externalContracts") or (intent.get("specialized") or {}).get("externalApis")):
+                raise HandoffError("entity selectors require entity metadata", "PLUGIN_CONTEXT_INCOMPLETE")
+        source_only = needs == [] and intent.get("ownershipMode") == "modify" and bool(intent.get("sourcePath"))
+        if source_only and args.plugin_type == "operation":
+            raise HandoffError("operation plugins require verified operation metadata", "PLUGIN_CONTEXT_INCOMPLETE")
+        if args.refresh_report_state and not artifact_paths:
+            raise HandoffError("--refresh-report-state requires --artifact or --emit-manifest", "PLUGIN_REPORT_STATE_INPUT_INVALID")
+        if args.form_number and artifact_paths and args.plugin_type in {"reportlist", "report-plugin", "reportform", "reporttreelist"}:
+            selected = _exact_one(_catalog(artifact_paths, run_result)[0], args.form_number, ("formNumber",), "form")
+            intent["form"] = selected["formNumber"]
+        if (args.form_number and args.plugin_type not in {"reportlist", "report-plugin", "reportform", "reporttreelist"}) or not artifact_paths or args.plugin_type == "operation":
             form_number = args.form_number or str(intent.get("form") or "")
             if not args.form_number and artifact_paths:
                 hints = (run_result or {}).get("forms") or _catalog(artifact_paths, run_result)[0]
                 form_number = _exact_one(hints, intent.get("form"), ("formName", "formNumber"), "form")["formNumber"]
-            if not re.fullmatch(r"[A-Za-z0-9_]+", form_number):
+            if not source_only and not re.fullmatch(r"[A-Za-z0-9_]+", form_number):
                 raise HandoffError("independent preparation requires --form-number with an exact existing form code")
-            runtime_metadata, operation_result = prepare_runtime_inputs(args.app_root, form_number, intent, args.plugin_type)
-            intent["form"] = form_number
+            requested_ui = set(needs or []) & {"form", "list"}
+            if requested_ui and "entity" in (needs or []):
+                from concurrent.futures import ThreadPoolExecutor
+                with ThreadPoolExecutor(max_workers=2) as pool:
+                    ui_read = pool.submit(read_ui_context, args.app_root, form_number, args.plugin_type,
+                                          include_list="list" in requested_ui)
+                    entity_read = pool.submit(prepare_runtime_inputs, args.app_root, form_number, intent, args.plugin_type,
+                                              operation_result=operation_result, external_schemas=external_schemas)
+                    ui_context = ui_read.result()
+                    runtime_metadata, operation_result = entity_read.result()
+            elif "list" in requested_ui:
+                ui_context = read_ui_context(args.app_root, form_number, args.plugin_type, include_list=True)
+            elif "form" in requested_ui:
+                ui_context = read_ui_context(args.app_root, form_number, args.plugin_type)
+            if needs is not None and "operate" in needs and (args.plugin_type != "operation" or "entity" not in needs):
+                operation_result = operation_result or read_platform(args.app_root, "listOperations", form_number)
+                _validate_operation_result(operation_result, form_number, args.app_root,
+                    _string_list(intent.get("operationKeys"), "operationKeys") if args.plugin_type == "operation" else [])
+                if args.plugin_type == "operation" and "entity" not in needs:
+                    operation_context = {"formNumber": form_number, "source": "listOperations"}
+            if needs is None or "entity" in needs:
+                if runtime_metadata is None:
+                    runtime_metadata, operation_result = prepare_runtime_inputs(args.app_root, form_number, intent, args.plugin_type,
+                        operation_result=operation_result, external_schemas=external_schemas)
+            elif not ui_context and not operation_context and not source_only:
+                raise HandoffError("a verified page context is required when entity metadata is omitted", "PLUGIN_CONTEXT_INCOMPLETE")
+            intent["form"] = "" if source_only else form_number
             artifact_paths = []
         else:
             operation_result, external_schemas = prepare_inputs(
                 app_root=args.app_root, intent=intent, plugin_type=args.plugin_type,
                 artifact_paths=artifact_paths, run_result=run_result, operation_result=operation_result,
-                external_schemas=[_read_json(path) for path in args.external_schemas or []])
+                external_schemas=external_schemas)
         result = prepare_handoff(
             app_root=args.app_root, project_root=args.project_root, plugin_type=args.plugin_type,
             intent=intent, artifact_paths=artifact_paths, run_result=run_result,
-            operation_result=operation_result, runtime_metadata=runtime_metadata,
-            external_schemas=([_read_json(path) for path in args.external_schemas or []]
-                              if runtime_metadata else external_schemas),
+            operation_result=operation_result, runtime_metadata=runtime_metadata, ui_context=ui_context, operation_context=operation_context, source_only=source_only, prepare_source=args.prepare_source,
+            refresh_report_state=args.refresh_report_state,
+            external_schemas=external_schemas,
         )
         destination = (Path(args.output).resolve() if args.output else Path(args.app_root).resolve()
                        / "_runtime" / "plugin-handoffs" / (result["handoff"]["className"] + ".json"))
         assert_handoff_replace(destination, result, args.replace_handoff)
+        result["inputFiles"] = [*input_files, *result.get("inputFiles", [])]
+        validate_input_files(result)
         if args.prepare_source:
             from plugin_target_sdk import verify_target_sdk
             result['handoff']['targetSdk'] = verify_target_sdk(result['handoff']['projectRoot'],
@@ -1468,17 +1848,37 @@ def main() -> None:
             target = Path(handoff["sourcePath"]).resolve()
             if not target.is_relative_to(Path(handoff["projectRoot"]).resolve() / "src" / "main" / "java"):
                 raise HandoffError("source preparation target is outside the verified Java module", "PLUGIN_SOURCE_INVALID")
+            validate_input_files(result)
             target.parent.mkdir(parents=True, exist_ok=True)
-            write_state(handoff["projectRoot"], handoff["className"], "coding",
-                        os.environ.get("LINGEE_SESSION_ID") or os.environ.get("OPENCODE_SESSION_ID"), emit=False)
-            handoff["sourceGate"] = {"state": "coding", "path": gate_path(handoff["projectRoot"], handoff["className"])}
+            # 保存的是门禁请求；实际写成功后才在响应中报告 coding。
+            handoff["sourceGate"] = {"requestedState": "coding", "path": gate_path(handoff["projectRoot"], handoff["className"])}
         destination.parent.mkdir(parents=True, exist_ok=True)
         result["handoffPath"] = str(destination)
-        destination.write_text(json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8")
+        validate_input_files(result)
+        import os
+        import uuid
+        temporary = destination.with_name(destination.name + "." + uuid.uuid4().hex + ".tmp")
+        try:
+            temporary.write_text(json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8")
+            os.replace(temporary, destination)
+        finally:
+            temporary.unlink(missing_ok=True)
+        if args.prepare_source:
+            # 快照落盘失败时不推进门禁；门禁失败也不输出准备成功。
+            try:
+                write_state(handoff["projectRoot"], handoff["className"], "coding",
+                            os.environ.get("LINGEE_SESSION_ID") or os.environ.get("OPENCODE_SESSION_ID"), emit=False)
+            except OSError as exc:
+                raise HandoffError("Coding context saved, but source gate unavailable; resolve directory authorization before editing or compiling",
+                                   "PLUGIN_SOURCE_GATE_UNAVAILABLE", details={"handoffPath": str(destination),
+                                     "sourcePath": handoff["sourcePath"], "gatePath": handoff["sourceGate"]["path"],
+                                     "codingStartCommand": [sys.executable, str(Path(__file__).with_name("query_plugin_handoff.py")), "coding-start", "--handoff", str(destination)],
+                                     "recovery": "The context can be read without repeating preparation. Do not probe alternative write paths, copy scripts or retry unchanged builds. Resolve the selected directory's authorization or ask for a revised delivery scope; the source gate remains unverified."}) from exc
+            result["sourcePreparation"] = {"state": "coding", "verified": True, "path": handoff["sourceGate"]["path"]}
         print(json.dumps(handoff_response(result, full_output=args.full_output), ensure_ascii=False))
-    except (HandoffError, json.JSONDecodeError, ValueError) as exc:
+    except (HandoffError, json.JSONDecodeError, ValueError, OSError) as exc:
         error_code = getattr(exc, "error_code", getattr(exc, "code", "PLUGIN_HANDOFF_UNRESOLVED"))
-        print(json.dumps({"status": False, "errorCode": error_code, "message": str(exc)}, ensure_ascii=False))
+        print(json.dumps({"status": False, "errorCode": error_code, "message": str(exc), **getattr(exc, "details", {})}, ensure_ascii=False))
         raise SystemExit(2)