@shundoo-ai/dsh-cosmic 1.0.19 → 1.0.21

package/skills/cosmic-build/skills/cosmic-meta-api/scripts/_core/build_receipts.py

@@ -0,0 +1,171 @@
+"""Durable per-artifact progress inside the existing runBatch result contract."""
+import copy
+import csv
+import hashlib
+import json
+import os
+from pathlib import Path
+import sys
+import threading
+import subprocess
+import time
+
+from .execution_errors import classify_execution_error
+from execution_binding import execution_binding
+
+
+def _atomic_json(path, value):
+    temporary = path.with_name(path.name + ".tmp")
+    temporary.write_text(json.dumps(value, ensure_ascii=False, indent=2), encoding="utf-8")
+    os.replace(temporary, path)
+
+
+def _path(value):
+    return os.path.normcase(os.path.realpath(value))
+
+
+def _targets(artifact):
+    return sorted(str(row.get("entityKey") or "").strip() for row in artifact.get("entities", [])
+                  if isinstance(row, dict) and not row.get("parentEntityId"))
+
+
+class BuildReceipts:
+    def __init__(self, app_root, app_id, environment, artifacts, *, resume_result=None, options=None, reconcile_only=False):
+        self.root = Path(app_root).resolve()
+        self.output = self.root / "_runtime" / "output"
+        self.output.mkdir(parents=True, exist_ok=True)
+        self.lock = threading.Lock()
+        self.artifacts = artifacts
+        self.options = options or []
+        self.identity = {"appRoot": str(self.root), "bizAppId": str(app_id), "environment": environment, "executionOptions": self.options}
+        self.previous = {}
+        if resume_result:
+            prior = json.loads(Path(resume_result).read_text(encoding="utf-8-sig"))
+            if reconcile_only and not prior.get("executionFinished"):
+                pid = prior.get("processId")
+                if not isinstance(pid, int):
+                    raise ValueError("BATCH_WRITE_RECONCILIATION_REQUIRED: legacy receipt has no process boundary")
+                if os.name == "nt":
+                    tasks = subprocess.check_output(["tasklist", "/FI", f"PID eq {pid}", "/FO", "CSV", "/NH"], text=True)
+                    active = any(len(row) > 1 and row[1] == str(pid) for row in csv.reader(tasks.splitlines()))
+                else:
+                    try:
+                        os.kill(pid, 0)
+                        active = True
+                    except ProcessLookupError:
+                        active = False
+                if active:
+                    raise ValueError("BATCH_WRITE_RECONCILIATION_REQUIRED: original execution is still active")
+            if prior.get("batchIdentity") != self.identity:
+                raise ValueError("BATCH_INPUT_IDENTITY_CHANGED: resume requires the same application and environment")
+            if prior.get("executionBinding") and prior["executionBinding"] != execution_binding() and not reconcile_only:
+                raise ValueError("SKILL_REVISION_MISMATCH: reconcile the old receipt with the current bound source first")
+            self.previous = {_path(row["artifactPath"]): row for row in prior.get("results", [])}
+            if set(self.previous) != {_path(p) for p in artifacts}:
+                raise ValueError("BATCH_INPUT_ARTIFACTS_CHANGED: resume with the original paths; correct only unwritten inputs in place")
+        self.receipt = {"processId": os.getpid(), "executionBinding": execution_binding(), "batchIdentity": self.identity, "appRoot": str(self.root),
+                        "artifactPaths": list(artifacts), "results": [],
+                        "resultPath": str(self.output / f"runBatch.{time.time_ns()}.json")}
+        self.result_path = Path(self.receipt["resultPath"])
+        seen = set()
+        for source, artifact in artifacts.items():
+            targets = _targets(artifact)
+            if (not targets or any(not target for target in targets)
+                    or len({number.casefold() for number in targets}) != len(targets)
+                    or seen.intersection(number.casefold() for number in targets)):
+                raise ValueError("BATCH_INPUT_TARGET_CONFLICT: each artifact needs unique exact root entity keys")
+            seen.update(number.casefold() for number in targets)
+            revision = hashlib.sha256(Path(source).read_bytes()).hexdigest()
+            prior = self.previous.get(_path(source))
+            if prior and (prior.get("ok") or prior.get("writeAttempted") is not False):
+                if not reconcile_only and (not prior.get("ok") or (prior.get("verification") or {}).get("status") != "pass"):
+                    raise ValueError("BATCH_WRITE_RECONCILIATION_REQUIRED: inspect retained/unknown targets from " + str(resume_result))
+                if prior.get("inputRevision") != revision:
+                    raise ValueError("BATCH_INPUT_SAVED_TARGET_CHANGED: use an existing-form writer for the affected object and references")
+            row = copy.deepcopy(prior) if prior and (prior.get("ok") or reconcile_only) else {
+                "artifact": Path(source).name, "artifactPath": source, "inputRevision": revision,
+                "targetNumbers": targets, "ok": False, "phase": "notStarted",
+                "writeAttempted": False, "elapsed_sec": 0.0,
+            }
+            row["reusedReceipt"] = bool(prior and prior.get("ok"))
+            self.receipt["results"].append(row)
+        self._save()
+
+    def _save(self):
+        rows = self.receipt["results"]
+        self.receipt["success"] = sum(row.get("ok") is True for row in rows)
+        self.receipt["failed"] = len(rows) - self.receipt["success"]
+        self.receipt["total"] = len(rows)
+        self.receipt["resume"] = {"python": sys.executable, "entry": execution_binding()["cosmicApi"], "command": "runBatch",
+                                  "arguments": ["--stdout", "runBatch", "--app-root", str(self.root),
+                                                "--resume-result", str(self.result_path), "--verify",
+                                                *self.options, "--artifacts", *self.artifacts]}
+        unresolved = [row for row in rows if row.get("writeAttempted") is not False
+                      and (not row.get("ok") or (row.get("verification") or {}).get("status") != "pass")]
+        self.receipt["resume"]["ready"] = not unresolved
+        self.receipt["reconcile"] = {"python": sys.executable, "entry": execution_binding()["cosmicApi"],
+                                     "arguments": [*self.receipt["resume"]["arguments"], "--reconcile-only"],
+                                     "requiresOriginalExecutionFinished": True, "platformEffect": "read"}
+        self.receipt["reconciliation"] = [{
+            "python": sys.executable, "entry": execution_binding()["cosmicApi"],
+            "artifactPath": row["artifactPath"],
+            "arguments": ["--stdout", "queryForms", "--app-root", str(self.root), "--keyword", number],
+            "instruction": "Read exact identity first; an arbitrary same-number object is not this batch's success receipt",
+        } for row in unresolved for number in row["targetNumbers"]]
+        self.receipt["notStartedArtifacts"] = [row["artifactPath"] for row in rows if row.get("writeAttempted") is False and not row.get("ok")]
+        _atomic_json(self.result_path, self.receipt)
+
+    def current(self, source):
+        return next(copy.deepcopy(row) for row in self.receipt["results"] if _path(row["artifactPath"]) == _path(source))
+
+    def reused(self, source):
+        return next((copy.deepcopy(row) for row in self.receipt["results"]
+                     if _path(row["artifactPath"]) == _path(source) and row.get("reusedReceipt")), None)
+
+    def start(self, source):
+        """Claim exact target identities before dispatch; interrupted claims stay unknown."""
+        with self.lock:
+            row = next(row for row in self.receipt["results"] if _path(row["artifactPath"]) == _path(source))
+            claims = []
+            for number in row["targetNumbers"]:
+                key = hashlib.sha256(json.dumps([{key: value for key, value in self.identity.items() if key != "executionOptions"}, number.casefold()], sort_keys=True).encode()).hexdigest()
+                claim = self.output / f"runBatch.target.{key}.json"
+                if claim.exists():
+                    owner = json.loads(claim.read_text(encoding="utf-8"))
+                    raise ValueError("BATCH_WRITE_RECONCILIATION_REQUIRED: previous write receipt " + owner["resultPath"])
+                claims.append(claim)
+            row.update(phase="writeUnknown", writeAttempted=None,
+                       claimPaths=[str(p) for p in claims], claimOwner=str(self.result_path))
+            self._save()
+            # O_EXCL protects independent processes as well as threads.
+            acquired = []
+            try:
+                for claim in claims:
+                    with claim.open("x", encoding="utf-8") as handle:
+                        json.dump({"resultPath": str(self.result_path), "artifactPath": source}, handle)
+                    acquired.append(claim)
+            except FileExistsError:
+                for claim in acquired:
+                    claim.unlink()
+                raise ValueError("BATCH_WRITE_RECONCILIATION_REQUIRED: concurrent creation owns this target")
+
+    def finish(self, source, result):
+        with self.lock:
+            row = next(row for row in self.receipt["results"] if _path(row["artifactPath"]) == _path(source))
+            row.update(result)
+            row["artifactPath"] = source
+            if row.get("writeAttempted") is False:
+                for claim in row.get("claimPaths", []):
+                    path = Path(claim)
+                    if path.is_file() and json.loads(path.read_text(encoding="utf-8")).get("resultPath") == row.get("claimOwner"):
+                        path.unlink()
+                row.pop("claimPaths", None)
+                row.pop("claimOwner", None)
+            if row.get("ok"):
+                row.pop("errorCategory", None)
+                row.pop("capabilityLimitConfirmed", None)
+            if not row.get("ok"):
+                row["errorCategory"] = classify_execution_error(row)
+                row["capabilityLimitConfirmed"] = row["errorCategory"] == "capability_limit"
+            self._save()
+            return copy.deepcopy(row)

package/skills/cosmic-build/skills/cosmic-meta-api/scripts/_core/cmd_apps.py

@@ -1280,13 +1280,32 @@ def do_add_unit(cfg, token, biz_app_id=None, biz_app_number=None,
     else:
         raise ValueError("addUnit 需要 --bizAppId 或 --bizAppNumber 之一")
 
+    if not str(number or "").strip():
+        return {
+            "status": False, "errorCode": "FUNCTIONAL_GROUP_CODE_REQUIRED",
+            "message": "addUnit requires a non-empty number; preserve the requested functional group code.",
+            "writeAttempted": False,
+        }
     payload["name"] = name
-    if number is not None:
-        payload["number"] = number
-    if description is not None:
-        payload["description"] = description
-    if seq is not None:
-        payload["seq"] = seq
+    payload["number"] = number
+    payload["description"] = name if description is None else description
+    if seq is None:
+        if parent_unit_id not in (None, ""):
+            return {"status": False, "errorCode": "FUNCTIONAL_GROUP_SEQ_UNAVAILABLE", "message": "A nested group needs an explicit sibling --seq", "writeAttempted": False}
+        try:
+            existing = do_list_units(cfg, token, biz_app_id=biz_app_id, biz_app_number=biz_app_number)
+        except Exception as exc:
+            return {"status": False, "errorCode": "FUNCTIONAL_GROUP_SEQ_UNAVAILABLE", "message": f"Cannot choose the next group sequence: {exc}", "writeAttempted": False}
+        units = (existing.get("data") or {}).get("units") if isinstance(existing, dict) else None
+        if not isinstance(units, list) or not _is_api_success(existing):
+            return {"status": False, "errorCode": "FUNCTIONAL_GROUP_SEQ_UNAVAILABLE", "message": "Cannot read existing groups to choose the next sequence", "writeAttempted": False}
+        known = [int(unit["seq"]) if isinstance(unit, dict) and str(unit.get("seq") if unit.get("seq") is not None else "").isdigit() else None for unit in units]
+        if any(value is None for value in known):
+            return {"status": False, "errorCode": "FUNCTIONAL_GROUP_SEQ_UNAVAILABLE", "message": "Existing group sequence is unavailable; pass an explicit --seq", "writeAttempted": False}
+        seq = max(known, default=0) + 1
+    if not isinstance(seq, int) or not 1 <= seq < 1000:
+        return {"status": False, "errorCode": "FUNCTIONAL_GROUP_SEQ_INVALID", "message": "Group sequence must be an integer from 1 to 999", "writeAttempted": False}
+    payload["seq"] = seq
     if parent_unit_id is not None:
         payload["parentUnitId"] = parent_unit_id
     if is_leaf is not None:

package/skills/cosmic-build/skills/cosmic-meta-api/scripts/_core/cmd_controls.py

@@ -27,6 +27,14 @@ _PARENT_TYPES = {
 }
 
 
+class ControlInputError(ValueError):
+    def __init__(self, missing_fields):
+        super().__init__(
+            "CONTROL_INPUT_INVALID: required fields missing: " + ", ".join(missing_fields)
+        )
+        self.recovery = {"missingFields": missing_fields}
+
+
 @lru_cache(maxsize=1)
 def _control_contract():
     with (_CONTRACT or contract_path("control-authoring.json")).open("r", encoding="utf-8-sig") as stream:
@@ -132,7 +140,22 @@ def validate_control_batch_input(intent):
     unknown = sorted(set(intent) - {"parent", "panel", "controls"})
     if unknown:
         raise ValueError(f"CONTROL_INPUT_INVALID: unknown top-level keys {unknown}")
+    controls = intent.get("controls")
+    missing_fields = (["controls"] if controls is None else []) + [
+        f"controls[{index}].{field}"
+        for index, item in enumerate(controls if isinstance(controls, list) else [])
+        if isinstance(item, dict)
+        for field in ("type", "name") if not str(item.get(field) or "").strip()
+    ]
     panel_input = intent.get("panel")
+    if isinstance(panel_input, dict) and not str(panel_input.get("name") or "").strip():
+        missing_fields.append("panel.name")
+    if missing_fields:
+        raise ControlInputError(missing_fields)
+    if not isinstance(controls, list) or not controls:
+        raise ValueError("CONTROL_INPUT_INVALID: controls must be a non-empty array")
+    if len(controls) > 50:
+        raise ValueError("CONTROL_BATCH_TOO_LARGE: at most 50 controls per call")
     if panel_input is not None and intent.get("parent"):
         raise ValueError(
             "CONTROL_INPUT_INVALID: use panel.parent when panel is declared"
@@ -148,10 +171,6 @@ def validate_control_batch_input(intent):
             )
         panel_name = str(panel_input.get("name") or "").strip()
         panel_parent = str(panel_input.get("parent") or "").strip()
-        if not panel_name or not panel_parent:
-            raise ValueError(
-                "CONTROL_INPUT_INVALID: panel.name and panel.parent are required"
-            )
         panel_key = str(panel_input.get("key") or "").strip() or (
             "panel_" + hashlib.sha1(panel_name.encode("utf-8")).hexdigest()[:12]
         )
@@ -172,11 +191,6 @@ def validate_control_batch_input(intent):
             "controlDefaults": presentation,
         }
     default_parent = panel["key"] if panel else str(intent.get("parent") or "").strip()
-    controls = intent.get("controls")
-    if not isinstance(controls, list) or not controls:
-        raise ValueError("CONTROL_INPUT_INVALID: controls must be a non-empty array")
-    if len(controls) > 50:
-        raise ValueError("CONTROL_BATCH_TOO_LARGE: at most 50 controls per call")
 
     contract = _control_contract()
     normalized = []
@@ -191,8 +205,6 @@ def validate_control_batch_input(intent):
             )
         control_type = _resolve_control_type(item.get("type"), contract)
         name = str(item.get("name") or "").strip()
-        if not name:
-            raise ValueError(f"CONTROL_INPUT_INVALID: controls[{index}].name is required")
         key = str(item.get("key") or "").strip() or (
             "ctl_" + hashlib.sha1(
                 f"{control_type}:{name}".encode("utf-8")
@@ -207,11 +219,6 @@ def validate_control_batch_input(intent):
             raise ValueError(f"CONTROL_KEY_DUPLICATE: {key}")
         seen.add(key.casefold())
         parent = str(item.get("parent") or default_parent).strip()
-        if not parent:
-            raise ValueError(
-                f"CONTROL_PARENT_REQUIRED: controls[{index}] requires parent "
-                "or one top-level parent"
-            )
         if panel and parent != panel["key"]:
             raise ValueError(
                 f"CONTROL_PANEL_CHILD_PARENT_CONFLICT: controls[{index}] "
@@ -257,6 +264,29 @@ def validate_control_batch_input(intent):
     return {"panel": panel, "controls": normalized}
 
 
+def control_input_schema():
+    """Publish the request shape and type properties from the validator's contract."""
+    contract = _control_contract()
+    return {
+        **contract["inputSchema"],
+        "x-commonProperties": {
+            name: {key: value for key, value in declaration.items() if key != "readProperty"}
+            for name, declaration in contract["commonProperties"].items()
+        },
+        "x-controlTypes": {
+            control_type: {
+                "aliases": spec.get("aliases") or [],
+                "properties": {
+                    name: {key: value for key, value in declaration.items() if key != "readProperty"}
+                    for name, declaration in _property_contract(control_type, contract).items()
+                    if name not in contract["commonProperties"]
+                },
+            }
+            for control_type, spec in contract["releasedTypes"].items()
+        },
+    }
+
+
 def control_catalog():
     """Return the released/specialized/deferred screenshot-control surface."""
     contract = _control_contract()
@@ -291,8 +321,10 @@ def _layout_index(root):
     return nodes
 
 
-def _resolve_parent(selector, nodes):
-    wanted = str(selector or "").strip()
+def _resolve_parent(selector, nodes, root_key=""):
+    wanted = str(selector or root_key or "").strip()
+    if not wanted:
+        raise ValueError("CONTROL_PARENT_UNRESOLVED: live form root has no key")
     if wanted in nodes:
         matches = [wanted]
     else:
@@ -347,12 +379,14 @@ def do_add_controls(cfg, token, form_id, form_number, intent):
             "CONTROL_FORM_READ_FAILED: "
             + (_extract_error_message(before) or "getFormSchema failed")
         )
-    before_nodes = _layout_index((before.get("data") or {}).get("formLayout"))
+    before_layout = (before.get("data") or {}).get("formLayout") or {}
+    before_nodes = _layout_index(before_layout)
+    root_key = str(before_layout.get("key") or "").strip()
     panel = normalized.get("panel")
     panel_parent = None
     structural_ops = []
     if panel:
-        panel_parent = _resolve_parent(panel["parent"], before_nodes)
+        panel_parent = _resolve_parent(panel["parent"], before_nodes, root_key)
         current_panel = before_nodes.get(panel["key"])
         if current_panel:
             node = current_panel.get("node") or {}
@@ -396,7 +430,7 @@ def do_add_controls(cfg, token, form_id, form_number, intent):
     existing = []
     moved = []
     for item in managed:
-        parent = panel["key"] if panel else _resolve_parent(item["parent"], before_nodes)
+        parent = panel["key"] if panel else _resolve_parent(item["parent"], before_nodes, root_key)
         if not panel:
             parent_type = str(
                 ((before_nodes.get(parent) or {}).get("node") or {}).get("type") or ""

package/skills/cosmic-build/skills/cosmic-meta-api/scripts/_core/cmd_fields.py

@@ -813,7 +813,7 @@ def _qf_resolve_target_entity(entity_key, entry, entity_name, entity_list, form_
         }
 
     if entity_name:
-        matched = [e for e in entity_list if e.get("entityName") == entity_name]
+        matched = [e for e in entity_list if entity_name in {e.get("entityName"), e.get("entityKey")}]
         if len(matched) == 1:
             e = matched[0]
             return e["entityKey"], {
@@ -1486,6 +1486,14 @@ def _combo_verify_after_modify(cfg, token, form_number, field_key,
     observed_options = []
     read = _api_call(cfg, token, "loadFullMetadata",
                      {"formNumber": form_number}, method="GET")
+    if not _is_api_success(read):
+        return {
+            "status": "readback_failed",
+            "exit_code": QUICKFIELD_EXIT["api_error"],
+            "message": "Combo options could not be read back; their saved state is unknown. "
+                       + (_extract_error_message(read) or "loadFullMetadata failed"),
+            "cause": read,
+        }
     if _is_api_success(read):
         section = ((read.get("data") or {}).get("entitymeta") or {})
         items = section.get("Items") or []
@@ -1525,8 +1533,7 @@ def _combo_verify_after_modify(cfg, token, form_number, field_key,
                 "status": "modify_failed",
                 "exit_code": QUICKFIELD_EXIT["api_error"],
                 "message": f"modifyMeta reported success but these options are absent on read-back: {missing}. "
-                           "That means the op located nothing - check that target carries "
-                           "value with the field key.",
+                           "Check the saved target and options before retrying.",
                 "options": observed_options,
             }
         return {"status": "ok", "exit_code": QUICKFIELD_EXIT["ok"],

package/skills/cosmic-build/skills/cosmic-meta-api/scripts/_core/cmd_formactions.py

@@ -1779,6 +1779,12 @@ def do_add_field(cfg, token, form_name, field_name, biz_word,
     # modelType, accepting the shortened spelling some deployments return. `writeAttempted`
     # covers the field write only: target preparation above may already have extended the form,
     # so report that separately rather than implying nothing happened.
+    if field_type == "RefBillField" and str(editable.get("modelType") or "").strip().casefold() in {"baseformmodel", "base"}:
+        return _extension_terminal(
+            "REF_BILL_OWNER_UNSUPPORTED",
+            "The current RefBillField writer requires a bill form. Resolve model/reference semantics; do not substitute a field type automatically.",
+            "preflight", extra={"editableTarget": editable, "writeAttempted": False,
+                                "extensionPerformed": bool(prepared_data.get("extensionPerformed"))})
     if str(editable.get("modelType") or "").strip().casefold() in {"reportformmodel", "report"}:
         return _extension_terminal(
             "REPORT_FIELD_NOT_ADDABLE",
@@ -1952,6 +1958,17 @@ def do_add_field(cfg, token, form_name, field_name, biz_word,
             "verification": detail_verification,
         },
     }
+_BATCH_FIELD_OPTIONS = {
+    "basedata": "basedata", "mulTable": "mul_table", "unitField": "unit_field",
+    "flexType": "flex_type", "refBaseField": "ref_base_field",
+    "refDisplayProp": "ref_display_prop", "asstTypeId": "asst_type_id", "asstType": "asst_type",
+}
+
+
+def _batch_field_options(field):
+    return {argument: field[key] for key, argument in _BATCH_FIELD_OPTIONS.items() if key in field}
+
+
 def validate_add_fields_input(fields):
     if not isinstance(fields, list) or not fields:
         raise ValueError("FIELD_BATCH_INVALID: expected a non-empty array")
@@ -1967,8 +1984,20 @@ def validate_add_fields_input(fields):
             if "combo" in field or "comboJson" in field:
                 raise ValueError(f"FIELD_BATCH_INVALID: fields[{index}] comboOptions conflicts with combo/comboJson")
             field["comboJson"] = field.pop("comboOptions")
-        if set(field) - {"name", "bizWord", "fieldType", "combo", "comboJson", "required", "panel", "before", "after", "fullLine"}:
-            raise ValueError(f"FIELD_BATCH_INVALID: fields[{index}] has unsupported keys")
+        if "reference" in field:
+            reference = field["reference"]
+            if (field.get("fieldType") not in {"BasedataField", "MulBasedataField"}
+                    or not isinstance(reference, dict) or reference.get("mode") != "platform"
+                    or set(reference) - {"mode", "formNumber"}
+                    or not isinstance(reference.get("formNumber"), str) or not reference["formNumber"].strip()):
+                raise ValueError(f"FIELD_BATCH_INVALID: fields[{index}].reference requires a platform formNumber for BasedataField/MulBasedataField")
+            if "basedata" in field and field["basedata"] != reference["formNumber"]:
+                raise ValueError(f"FIELD_BATCH_INVALID: fields[{index}].reference conflicts with basedata")
+            field["basedata"] = reference["formNumber"]
+            field.pop("reference")
+        unknown = set(field) - {"name", "bizWord", "fieldType", "combo", "comboJson", "required", "panel", "before", "after", "fullLine"} - set(_BATCH_FIELD_OPTIONS)
+        if unknown:
+            raise ValueError(f"FIELD_BATCH_INVALID: fields[{index}] has unsupported keys: {sorted(unknown)}")
         if "required" in field and not isinstance(field["required"], bool):
             raise ValueError(f"FIELD_BATCH_INVALID: fields[{index}].required must be boolean")
         if "fullLine" in field and not isinstance(field["fullLine"], bool):
@@ -1989,7 +2018,8 @@ def validate_add_fields_input(fields):
                     "comboJson/comboOptions with explicit stable values"
                 )
         result = validate_add_field_input(field.get("name"), field.get("bizWord"), field.get("fieldType", "TextField"),
-                                          combo=field.get("combo"), combo_json=field.get("comboJson"))
+                                          combo=field.get("combo"), combo_json=field.get("comboJson"),
+                                          **_batch_field_options(field))
         if not result.get("status"):
             raise ValueError(f"FIELD_BATCH_INVALID: fields[{index}]: {result.get('message')}")
         if field["bizWord"] in words:
@@ -2016,7 +2046,7 @@ def do_add_fields(cfg, token, form_name, fields, *, app_root=None, project_root=
             field_type=field.get("fieldType", "TextField"), combo=field.get("combo"), combo_json=field.get("comboJson"),
             required=field.get("required", False), app_root=app_root, project_root=project_root,
             app_name=app_name, app_code=app_code, entry=entry, entity_name=entity_name, entity_key=entity_key,
-            _prepared=prepared)
+            _prepared=prepared, **_batch_field_options(field))
         results.append(result)
         if not _is_api_success(result) or not (result.get("data") or {}).get("verified"):
             return {"status": False, "errorCode": "FIELD_BATCH_INCOMPLETE",
@@ -2062,6 +2092,32 @@ def summary_delete_dependencies(metadata, fields):
     return dependencies
 
 
+def rule_delete_dependencies(metadata, fields):
+    """Find persisted rule references, excluding prose and unrelated layout links."""
+    keys = {field["fieldKey"] for field in fields}
+    patterns = {key: _re.compile(r"(?<![A-Za-z0-9_])" + _re.escape(key) + r"(?![A-Za-z0-9_])") for key in keys}
+    reference_slots = {"precondition", "condition", "triggerfield", "fieldnames", "fieldname",
+                       "targetfield", "srcfield", "expression", "fieldkey"}
+    found = []
+
+    def visit(value, rule=None, path=""):
+        if isinstance(value, list):
+            for index, child in enumerate(value):
+                visit(child, rule, f"{path}/{index}")
+        if not isinstance(value, dict):
+            return
+        if str(value.get("_Type_") or "").rsplit(".", 1)[-1] in {"BizRule", "FormRule"}:
+            rule = value.get("Id") or value.get("Key") or path
+        for slot, child in value.items():
+            if rule is not None and slot.lower() in reference_slots and isinstance(child, str):
+                for key, pattern in patterns.items():
+                    if pattern.search(child):
+                        found.append({"ruleId": rule, "property": f"{path}/{slot}", "targetField": key})
+            visit(child, rule, f"{path}/{slot}")
+    visit(metadata)
+    return found
+
+
 def do_remove_field(cfg, token, form_name, field_name, *, app_root=None,
                     project_root=None, app_name=None, app_code=None,
                     entity_key=None, before_delete=None):
@@ -2155,10 +2211,11 @@ def do_remove_field(cfg, token, form_name, field_name, *, app_root=None,
     if not _is_api_success(metadata) or not isinstance(metadata.get("data"), dict):
         return _extension_terminal("FIELD_DEPENDENCY_READ_FAILED", "删除前无法校验字段依赖关系",
                                    "preflight", cause=metadata, extra={"writeAttempted": False})
-    dependencies = summary_delete_dependencies(metadata.get("data"), candidates)
+    dependencies = (summary_delete_dependencies(metadata.get("data"), candidates)
+                    + rule_delete_dependencies(metadata.get("data"), candidates))
     if dependencies:
         return _extension_terminal("FIELD_DELETE_DEPENDENCY_BLOCKED",
-            "仍有字段引用本次待删除的字段。请先厘清预期的业务关系再删除任何字段；不要清空该关系，也不要创建临时目标来绕过。",
+            "Surviving fields or rules reference the requested deletion. Resolve the intended business relationship before deleting any fields; do not clear it or create a temporary target as a workaround.",
             "preflight", extra={"writeAttempted": False, "dependencies": dependencies, "fields": candidates,
                                 "editableTarget": editable})
     field = candidates[0]

package/skills/cosmic-build/skills/cosmic-meta-api/scripts/_core/cmd_forms.py

@@ -31,17 +31,73 @@ def do_query_forms_by_app(cfg, token, app_number=None, cloud_number=None, keywor
     return _api_call(cfg, token, "queryFormsByApp", payload, method="GET")
 # ─── queryPublicTemplates / queryBizTemplates ────────────────────────────────
 
+_TEMPLATE_MODEL_ALIASES = {
+    "FormModel_Bill": "BillFormModel",
+    "FormModel_Base": "BaseFormModel",
+}
+
+
+def _template_model_type(value):
+    return _TEMPLATE_MODEL_ALIASES.get(value, value)
+
+def normalize_template_caption(value):
+    text = str(value or "").strip().replace("模版", "模板")
+    text = _re.sub(r"[\s()（）]+", "", text)
+    return text[:-2] if text.endswith("模板") else text
+
+
+def resolve_template_selector(selector, templates, model_type=None):
+    """Resolve an exact live template code or unique name within the model type."""
+    wanted = str(selector or "").strip()
+    model_type = _template_model_type(model_type)
+    rows = [row for row in templates if isinstance(row, dict)
+            and (not model_type or _template_model_type(row.get("modelType")) == model_type)]
+    coded = [row for row in rows if str(row.get("number") or "").strip() == wanted]
+    if len(coded) == 1:
+        return coded[0]["number"]
+    exact_names = {str(row["number"]) for row in rows if row.get("number")
+                   and str(row.get("name") or "").strip() == wanted}
+    if len(exact_names) == 1:
+        return next(iter(exact_names))
+    # 模版 and 模板 are spelling variants, not different template identities.
+    normalize = normalize_template_caption
+    matched = {str(row["number"]) for row in rows
+               if row.get("number") and normalize(row.get("name")) == normalize(wanted)}
+    if len(matched) == 1:
+        return next(iter(matched))
+    if matched:
+        raise ValueError(f"TEMPLATE_NAME_AMBIGUOUS: {wanted}: {sorted(matched)}")
+    raise ValueError(f"TEMPLATE_NOT_FOUND: {wanted}")
+
+
+def resolve_template_input(cfg, token, selector, *, biz_app_id=None, biz_app_number=None, model_type=None):
+    wanted = str(selector or "").strip()
+    if not wanted:
+        return wanted
+    rows = do_get_template_list(cfg, token,
+        model_types=[model_type] if model_type else None,
+        biz_app_id=biz_app_id, biz_app_number=biz_app_number)
+    if not rows:
+        return wanted
+    try:
+        return resolve_template_selector(wanted, rows, model_type)
+    except ValueError as exc:
+        if str(exc).startswith("TEMPLATE_NOT_FOUND") and _re.fullmatch(r"[A-Za-z][A-Za-z0-9_]*", wanted):
+            return wanted
+        raise
+
+
 def do_query_public_templates(cfg, token, model_type="BillFormModel",
                               biz_app_number=None):
     """Query public template list."""
-    payload = {"modelType": model_type}
+    payload = {"modelType": _template_model_type(model_type)}
     if biz_app_number:
         payload["bizAppNumber"] = biz_app_number
     return _api_call(cfg, token, "queryPublicTemplates", payload, method="POST")
 def do_query_biz_templates(cfg, token, model_type="BillFormModel",
                            biz_app_id=None, biz_app_number=None):
     """Query business template list (app required)."""
-    payload = {"modelType": model_type}
+    payload = {"modelType": _template_model_type(model_type)}
     if biz_app_id:
         payload["bizAppId"] = biz_app_id
     if biz_app_number:
@@ -73,6 +129,7 @@ def do_get_template_list(cfg, token, model_types=None, biz_app_id=None, biz_app_
     """
     if model_types is None:
         model_types = ["BillFormModel", "BaseFormModel"]
+    model_types = list(dict.fromkeys(_template_model_type(mt) for mt in model_types))
     all_templates: list[dict] = []
     seen_numbers: set[str] = set()
     for mt in model_types:

package/skills/cosmic-build/skills/cosmic-meta-api/scripts/_core/cmd_listui.py

@@ -1488,6 +1488,14 @@ def do_configure_list(
         return _list_configuration_preflight_failure(
             "LIST_CONFIGURATION_BASELINE_FAILED",
             "写入列表前无法同时读取设计态和运行态元数据",
+            failedReads={
+                name: item
+                for name, item in (
+                    ("listElements", field_result), ("getFormSchema", schema_before),
+                    ("loadFullMetadata", metadata_before), ("getEntityType", entity_type),
+                )
+                if not _is_api_success(item)
+            },
         )
 
     field_rows = field_result.get("data") or []