@shundoo-ai/dsh-cosmic 1.0.19 → 1.0.21

package/skills/cosmic-build/skills/cosmic-meta-modeling/scripts/data_model_emit.py

@@ -97,6 +97,7 @@ from isv_resolver import resolve_developer_identity, resolve_isv  # noqa: E402
 from project_paths import ensure_app_runtime_ignore  # noqa: E402
 
 _ENTITY_BIZNAME_RE = re.compile(r"^[A-Za-z][A-Za-z0-9_]*$")
+_DEFAULT_ENTITY_TEMPLATES = {"BillEntity": "bos_billtpl", "BaseEntity": "bos_basetpl"}
 
 try:
     from kd_env_loader import get_locale, resolve_locale  # noqa: E402
@@ -190,6 +191,8 @@ def _run_cosmic_api(
             timeout=60,
         )
         if proc.returncode != 0:
+            detail = (proc.stdout or proc.stderr or "").strip()
+            print(f"[cosmic-api] {command} failed (exit={proc.returncode}): {detail}", file=sys.stderr)
             return None
         output = (proc.stdout or "").strip()
         if not output:
@@ -568,7 +571,7 @@ def _apply_direct_authoring_constraints(
     for entity in entities:
         if not isinstance(entity, dict) or "templateKey" in entity:
             continue
-        default = {"BillEntity": "bos_billtpl", "BaseEntity": "bos_basetpl"}.get(str(entity.get("type") or ""))
+        default = _DEFAULT_ENTITY_TEMPLATES.get(str(entity.get("type") or ""))
         if default:
             entity["templateKey"] = default
     for entity in entities:
@@ -1196,7 +1199,8 @@ def _extract_resolver_field_writes(dm_section: dict[str, Any]) -> dict[str, dict
 def shape_check(dm_section: dict[str, Any], logs: _Logs) -> bool:
     """artifact + assumptions structural compliance validation.
 
-    - artifact.entities[]: required non-empty array; each item must have bizName/displayName/type/templateKey/fields[]
+    - artifact.entities[]: required non-empty array; each item has bizName/displayName/type/fields[];
+      BillEntity/BaseEntity receive a standard template when templateKey is omitted
     - assumptions[]: array (can be empty)
 
     Returns True for pass; False for SHAPE_INVALID errors.
@@ -2167,77 +2171,60 @@ def _extend_platform_carry_field_keys(
     return True
 
 
-def _validate_template_keys(dm_section: dict[str, Any], logs: _Logs, cosmic_api_path: str) -> bool:
+def _validate_template_keys(
+    dm_section: dict[str, Any], logs: _Logs, cosmic_api_path: str, *, app_root: Path,
+) -> bool:
     """Validate each entity's templateKey legality.
 
-    Call getTemplateList to get public + business template list (with source annotation),
-    stop emit if templateKey is not in the list, requiring user selection.
+    Read the applicable public and app template catalogs before emission. A
+    failed catalog call is not an empty catalog, and an exact template can also
+    be proved by its preset-field readback when a server omits it from lists.
     """
     artifact = dm_section.get("artifact") or {}
     entities = artifact.get("entities") or []
 
     biz_app_number = ""
-    ctx_path = dm_section.get("_section_io") or {}
-    app_root = ctx_path.get("app_root") or ""
-    if app_root:
-        ctx_file = Path(app_root) / "_runtime" / "context.json"
-        if ctx_file.exists():
-            try:
-                ctx = json.loads(ctx_file.read_text(encoding="utf-8"))
-                biz_app_number = str(ctx.get("appCode") or "").strip()
-            except Exception:
-                pass
-
-    available_templates: dict[str, dict] = {}
-    model_types = ["BillFormModel", "BaseFormModel"]
-    for mt in model_types:
+    ctx_file = app_root / "_runtime" / "context.json"
+    if ctx_file.exists():
         try:
-            pub_cmd = [sys.executable, cosmic_api_path, "--json",
-                       "queryPublicTemplates", "--modelType", mt]
-            if biz_app_number:
-                pub_cmd.extend(["--bizAppNumber", biz_app_number])
-            proc = subprocess.run(pub_cmd, capture_output=True, text=True,
-                                 encoding="utf-8", errors="replace", timeout=60)
-            if proc.returncode == 0 and (proc.stdout or "").strip():
-                result = json.loads(proc.stdout.strip())
-                templates = (result.get("data") or {}).get("templates") or []
-                if isinstance(templates, list):
-                    for t in templates:
-                        if isinstance(t, dict):
-                            num = str(t.get("number") or "").strip()
-                            if num:
-                                available_templates[num] = {
-                                    "name": str(t.get("name") or ""),
-                                    "modelType": str(t.get("modelType") or mt),
-                                    "source": "public",
-                                }
+            ctx = json.loads(ctx_file.read_text(encoding="utf-8"))
+            biz_app_number = str(ctx.get("appCode") or "").strip()
         except Exception:
-            logs.warn("API-UNAVAILABLE", f"queryPublicTemplates({mt}) call failed",
-                      en=f"queryPublicTemplates({mt}) call failed")
+            pass
 
-        try:
-            biz_cmd = [sys.executable, cosmic_api_path, "--json",
-                       "queryBizTemplates", "--modelType", mt]
-            if biz_app_number:
-                biz_cmd.extend(["--bizAppNumber", biz_app_number])
-            proc = subprocess.run(biz_cmd, capture_output=True, text=True,
-                                 encoding="utf-8", errors="replace", timeout=60)
-            if proc.returncode == 0 and (proc.stdout or "").strip():
-                result = json.loads(proc.stdout.strip())
-                templates = (result.get("data") or {}).get("templates") or []
-                if isinstance(templates, list):
-                    for t in templates:
-                        if isinstance(t, dict):
-                            num = str(t.get("number") or "").strip()
-                            if num:
-                                available_templates[num] = {
-                                    "name": str(t.get("name") or ""),
-                                    "modelType": str(t.get("modelType") or mt),
-                                    "source": "biz",
-                                }
-        except Exception:
-            logs.warn("API-UNAVAILABLE", f"queryBizTemplates({mt}) call failed",
-                      en=f"queryBizTemplates({mt}) call failed")
+    available_templates: list[dict[str, str]] = []
+    successful_types: set[str] = set()
+    failed_sources: dict[str, set[str]] = {}
+    model_type_by_entity = {"BillEntity": "BillFormModel", "BaseEntity": "BaseFormModel"}
+    model_types = sorted({
+        model_type_by_entity[ent.get("type")]
+        for ent in entities if isinstance(ent, dict) and ent.get("type") in model_type_by_entity
+    })
+    bound_root = app_root.resolve()
+    for mt in model_types:
+        queries = [("queryPublicTemplates", {"modelType": mt}, "public")]
+        if biz_app_number:
+            queries.append(("queryBizTemplates", {
+                "modelType": mt, "bizAppNumber": biz_app_number,
+            }, "biz"))
+        for command, arguments, source in queries:
+            result = _run_cosmic_api(
+                cosmic_api_path, command, arguments, app_root=bound_root,
+            )
+            data = result.get("data") if isinstance(result, dict) else None
+            templates = data.get("templates") if isinstance(data, dict) else None
+            if (not isinstance(result, dict) or result.get("status") is not True
+                    or not isinstance(data, dict) or data.get("success") is False
+                    or not isinstance(templates, list)):
+                failed_sources.setdefault(mt, set()).add(source)
+                continue
+            successful_types.add(mt)
+            available_templates.extend({
+                "number": str(row.get("number") or "").strip(),
+                "name": str(row.get("name") or ""),
+                "modelType": mt,
+                "source": source,
+            } for row in templates if isinstance(row, dict) and row.get("number"))
 
     ok = True
     for ent in entities:
@@ -2253,21 +2240,42 @@ def _validate_template_keys(dm_section: dict[str, Any], logs: _Logs, cosmic_api_
                      en=f"Entity '{ent.get('bizName')}' (type={etype}) missing templateKey, please specify")
             ok = False
             continue
-        if available_templates and tk not in available_templates:
-            matching_by_name = [
-                f"{num} ({info['name']}) [{info['source']}]"
-                for num, info in available_templates.items()
-                if info.get("modelType", "").startswith(
-                    "Bill" if etype == "BillEntity" else "Base"
-                )
-            ]
-            logs.err("INVALID-TEMPLATEKEY",
-                     f"Entity '{ent.get('bizName')}' templateKey='{tk}' not in available templates. "
-                     f"Please provide the correct template code or let the user choose."
-                     f"Available: {matching_by_name[:10]}",
-                     en=f"Entity '{ent.get('bizName')}' templateKey='{tk}' not in available templates. "
-                     f"Available: {matching_by_name[:10]}")
-            ok = False
+        expected_model = model_type_by_entity.get(etype)
+        if not expected_model:
+            continue
+        _ensure_field_decorator_on_path()
+        from _core.cmd_forms import resolve_template_selector
+        try:
+            resolved_template = resolve_template_selector(tk, available_templates, expected_model)
+        except ValueError:
+            resolved_template = None
+        if resolved_template:
+            ent["templateKey"] = resolved_template
+            if tk != resolved_template:
+                logs.info("TEMPLATE-NAME-RESOLVED", f"{tk} -> {resolved_template}")
+            continue
+        detail = _run_cosmic_api(cosmic_api_path, "getEntityFields", {
+            "formNumber": tk,
+        }, app_root=bound_root) if tk != "blankPage" else None
+        detail_data = detail.get("data") if isinstance(detail, dict) else None
+        header = detail_data.get("headerFields") if isinstance(detail_data, dict) else None
+        if isinstance(header, dict) and header.get("headerKey") == tk:
+            logs.warn("TEMPLATE-NOT-LISTED", f"{tk} exists but was absent from template lists",
+                      en=f"{tk} exists but was absent from template lists")
+            continue
+        candidates = [
+            f"{row['number']} ({row['name']}) [{row['source']}]"
+            for row in available_templates if row["modelType"] == expected_model
+        ]
+        lookup_incomplete = (expected_model not in successful_types
+                             or "biz" in failed_sources.get(expected_model, set()))
+        error_code = "TEMPLATE-LOOKUP-UNAVAILABLE" if lookup_incomplete else "INVALID-TEMPLATEKEY"
+        logs.err(error_code,
+                 f"Entity '{ent.get('bizName')}' templateKey='{tk}' could not be verified. "
+                 f"Available: {candidates[:10]}",
+                 en=f"Entity '{ent.get('bizName')}' templateKey='{tk}' could not be verified. "
+                 f"Available: {candidates[:10]}")
+        ok = False
     return ok
 
 
@@ -3389,7 +3397,8 @@ def _normalize_ui_composition_contract(value: Any) -> Any:
                 if not isinstance(row, dict) or set(row) != {"fields"}:
                     raise ValueError(
                         f"uiComposition.{collection_name}[{block_index}].rows"
-                        f"[{row_index}] must contain only fields"
+                        f"[{row_index}] must contain only fields; put fullLine "
+                        'inside a fields[] item, e.g. {"fields":[{"field":"Description","fullLine":true}]}'
                     )
                 fields = row.get("fields")
                 if not isinstance(fields, list) or not fields:
@@ -3648,8 +3657,8 @@ def assemble_artifact_emit(
                 continue
             field_biz = str(field.get("bizWord") or "")
             if entity_biz and field_biz:
-                field_key = str(field.get("logicalName") or "").strip() or make_field_key(
-                    field_biz, isv, standard=standard
+                field_key = make_field_key(
+                    str(field.get("logicalName") or "").strip() or field_biz, isv, standard=standard
                 )
                 source_field_keys[(entity_biz, field_biz)] = field_key
                 source_field_keys[(entity_key, field_biz)] = field_key
@@ -4688,8 +4697,8 @@ def _print_repair_report(logs: _Logs, exit_code: int) -> None:
         if is_en:
             print("==== REPAIR HINT: templateKey error ====", file=sys.stderr)
             print(
-                "Entity has missing or invalid templateKey.\n"
-                "  -> Each BillEntity/BaseEntity MUST have a templateKey field.\n"
+                "Entity has an empty or invalid templateKey.\n"
+                "  -> Omit templateKey to use the standard BillEntity/BaseEntity default.\n"
                 "  -> Standard templates: bos_billtpl, bos_billorgtpl, bos_basetpl, etc.\n"
                 "  -> If user specified a custom template, provide the exact template number.",
                 file=sys.stderr,
@@ -4697,8 +4706,8 @@ def _print_repair_report(logs: _Logs, exit_code: int) -> None:
         else:
             print("==== REPAIR HINT: templateKey error ====", file=sys.stderr)
             print(
-                "Entity has missing or invalid templateKey.\n"
-                "  → Each BillEntity/BaseEntity MUST have a templateKey field.\n"
+                "Entity has an empty or invalid templateKey.\n"
+                "  → Omit templateKey to use the standard BillEntity/BaseEntity default.\n"
                 "  → Standard templates: bos_billtpl, bos_billorgtpl, bos_basetpl, etc.\n"
                 "  → If user specified a custom template, provide the exact template number.",
                 file=sys.stderr,
@@ -4843,7 +4852,40 @@ def main(argv: list[str] | None = None) -> int:
         help="Artifact output directory; default is metadata/_emit/<run-id>.",
     )
     parser.add_argument("--quiet", action="store_true", help="only output on errors")
-    args = parser.parse_args(argv)
+    parser.add_argument("--describe", action="store_true", help="Return the existing authoring schema and executable contract without platform access")
+    arguments = list(argv) if argv is not None else sys.argv[1:]
+    if "--describe" in arguments:
+        if arguments != ["--describe"]:
+            parser.error("--describe is read-only and takes no execution arguments")
+        root = Path(__file__).resolve().parents[3]
+        schema_file = root / "schemas" / "data-model-authoring.schema.json"
+        schema = json.loads(schema_file.read_text(encoding="utf-8"))
+        authoring_contract = {
+            "callerFieldInputs": schema["definitions"]["field"]["required"],
+            "compilerGeneratedIdentifiers": ["formNumber", "entityKey", "tableName", "fieldKey", "columnName"],
+            "explicitIdentifierOverrides": ["--root-form-number", "logicalName", "physicalName"],
+            "defaultTemplates": _DEFAULT_ENTITY_TEMPLATES,
+            "guidance": {
+                "en": "Define business fields using semantic bizWord, displayName and dataType. Omit templateKey unless a specific template is requested. The compiler resolves templates, fetches live header/entry preset fields, reuses exact-key overlaps, and generates identifiers with naming/collision rules. Do not reproduce these algorithms or inspect source before authoring; the schema and returned validation errors own the contract. Explicit user identifiers remain constraints. Query template fields separately only when business behavior needs an exact preset-field identity; unknown field types use fieldTypesCommand, known types need no catalog lookup.",
+                "zh": "按业务语义填写 bizWord、displayName、dataType；未指定模板时省略 templateKey。编译器负责模板解析、动态读取表头/分录预置字段、按准确键复用重叠字段，以及标识生成和命名冲突处理。编写输入前无需复刻算法或读源码，以 Schema 和返回的校验错误为准；用户明确指定的标识仍是约束。仅当业务行为需要准确预置字段身份时，单独查询模板字段；未知类型用 fieldTypesCommand，已知类型不查目录。",
+            },
+            "templateFieldInspection": {
+                "argv": [sys.executable, str(root / "skills/cosmic-meta-api/scripts/cosmic_api.py"),
+                         "--stdout", "getEntityFields", "--app-root", "<verified-app-root>",
+                         "--formNumber", "<template-key>"],
+                "templateKeySource": "explicit templateKey or defaultTemplates[entity.type]",
+                "responsePaths": ["data.headerFields.fields", "data.entryFields.fields"],
+            },
+        }
+        print(json.dumps({"command": "data_model_emit", "execution": {"argvPrefix": [sys.executable, str(Path(__file__).resolve())]},
+                          "authoringContract": authoring_contract,
+                          "arguments": [{"flags": action.option_strings, "required": action.required,
+                                         "help": action.help} for action in parser._actions if action.dest not in {"help", "describe"}],
+                          "schemaPath": str(schema_file), "inputSchema": schema,
+                          "fieldTypesCommand": [sys.executable, str(Path(__file__).resolve().with_name("field_type_registry.py")), "--catalog", "--compact"]},
+                         ensure_ascii=False, separators=(",", ":")))
+        return EXIT_SUCCESS
+    args = parser.parse_args(arguments)
 
     app_root = Path(args.app_root).resolve()
     if not app_root.exists():
@@ -5024,7 +5066,7 @@ def main(argv: list[str] | None = None) -> int:
     cosmic_api_path = str(
         Path(__file__).resolve().parents[2] / "cosmic-meta-api" / "scripts" / "cosmic_api.py"
     )
-    if not _validate_template_keys(dm_section, logs, cosmic_api_path):
+    if not _validate_template_keys(dm_section, logs, cosmic_api_path, app_root=app_root):
         _persist_data_model_section(section_io, dm_section, logs)
         _print_repair_report(logs, EXIT_IR_INVALID)
         return EXIT_IR_INVALID
@@ -5106,6 +5148,12 @@ def main(argv: list[str] | None = None) -> int:
 
     logs.clear_error_report()
 
+    # The compiler already knows the manifest. Pass it onward without another
+    # filesystem read or model-authored command reconstruction.
+    root = Path(__file__).resolve().parents[3]
+    next_argv = [sys.executable, str(root / "skills" / "cosmic-meta-api" / "scripts" / "cosmic_api.py"),
+                 "runBatch", "--app-root", str(app_root), "--emit-manifest", str(output_dir / "_emit_manifest.json"), "--verify"]
+    print("NEXT_COMMAND=" + json.dumps(next_argv, ensure_ascii=False))
     print(f"EMIT_SUCCESS: {len(written)} artifact written to {output_dir}")
     return EXIT_SUCCESS
 

package/skills/cosmic-build/skills/cosmic-meta-modeling/scripts/field_type_registry.py

@@ -117,10 +117,20 @@ def main(argv: list[str] | None = None) -> int:
         action="store_true",
         help="print the complete document-backed field-type catalog as JSON",
     )
+    parser.add_argument("--types", nargs="+", help="Exact FieldDataType names to describe; no semantic guessing")
+    parser.add_argument("--compact", action="store_true", help="Return the semantic index only, without full constraints")
     args = parser.parse_args(argv)
     if not args.catalog:
         parser.error("--catalog is required")
-    print(json.dumps(build_field_type_catalog(), ensure_ascii=False, indent=2))
+    catalog = build_field_type_catalog()
+    if args.types:
+        missing = sorted(set(args.types) - {item["name"] for item in catalog["fieldTypes"]})
+        if missing:
+            parser.error("Unknown FieldDataType: " + ", ".join(missing))
+        catalog["fieldTypes"] = [item for item in catalog["fieldTypes"] if item["name"] in args.types]
+    if args.compact:
+        catalog["fieldTypes"] = [{key: item[key] for key in ("name", "semantics", "manualForbidden")} for item in catalog["fieldTypes"]]
+    print(json.dumps(catalog, ensure_ascii=False, separators=(",", ":")))
     return 0
 
 

package/skills/cosmic-build/skills/cosmic-meta-modeling/scripts/isv_resolver.py

@@ -88,9 +88,7 @@ def _fetch_isv_via_get_dev_info(app_root: Path) -> tuple[str, Any]:
     except Exception as exc:
         raise IsvResolveError(f"Unable to load cosmic-meta-api._core: {exc}") from exc
 
-    target = app_root / "_runtime" / "cosmic-metadata"
-    target.mkdir(parents=True, exist_ok=True)
-    _cfg._init_paths(temp_dir=str(target))
+    _cfg._init_paths(app_root=app_root)
 
     try:
         cfg = _cfg.load_config()

package/skills/cosmic-build/skills/cosmic-meta-modeling/scripts/report_validator.py

@@ -509,11 +509,36 @@ def validate_report_artifact(artifact):
 # CLI
 # ═══════════════════════════════════════════════════════════════════════════════
 
+def report_artifact_schema():
+    """Publish the artifact and its payload definitions as one local schema."""
+    schema = json.loads((Path(__file__).resolve().parents[1] / "modules/report/report-artifact-schema.json").read_text(encoding="utf-8"))
+    contract = json.loads((API_SCRIPTS.parent / "contracts/schema/report-write.schema.json").read_text(encoding="utf-8"))
+
+    def rewrite(value, external=False):
+        if isinstance(value, list):
+            return [rewrite(item, external) for item in value]
+        if not isinstance(value, dict):
+            return value
+        result = {key: rewrite(item, external) for key, item in value.items()}
+        reference = result.get("$ref", "")
+        prefix = "#/$defs/" if external else "app-build://cosmic-meta-api/report-write.schema.json#/$defs/"
+        if reference.startswith(prefix):
+            result["$ref"] = "#/$defs/reportWrite_" + reference[len(prefix):]
+        return result
+
+    bundled = rewrite(schema)
+    bundled.setdefault("$defs", {}).update({
+        "reportWrite_" + key: rewrite(value, True) for key, value in contract["$defs"].items()
+    })
+    return bundled
+
+
 def _build_parser():
     parser = argparse.ArgumentParser(
         description="Validate report-specific sections of a Cosmic Artifact."
     )
     group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument("--schema", action="store_true", help="Print the complete report artifact schema without platform access.")
     group.add_argument(
         "--artifact",
         metavar="PATH",
@@ -572,6 +597,10 @@ def main():
     parser = _build_parser()
     args = parser.parse_args()
 
+    if args.schema:
+        print(json.dumps(report_artifact_schema(), ensure_ascii=False, indent=2))
+        return
+
     artifact = _load_artifact(args)
     result = validate_report_artifact(artifact)
 

package/skills/cosmic-build/skills/cosmic-meta-modifier/SKILL.md

@@ -6,7 +6,7 @@ description: app-build 内部执行技能，用确定性 CLI 修改已有苍穹
 # 已有表单元数据修改
 
 使用原始意图和准确目标，执行最小可验证 CLI 闭环。
-`ROOT_DIR` 是已加载的 app-build 根 `SKILL.md` 所在目录；直接使用下方准确发布路径。
+`{ROOT_DIR}` 是已加载的 app-build 根 `SKILL.md` 所在目录；直接使用下方准确发布路径。
 
 只有用户明确提供的准确应用目录，或成功绑定命令返回的目录，才是可信 `appRoot`；不得把
 项目根或其 `app/` 目录提升为 `appRoot`。用户明确删除一个准确元数据元素时可原子删除，
@@ -135,6 +135,7 @@ MetaOps 或再次确认。
 常用规则意图直达小型 rule-domain 命令：
 
 - `ensureFieldCalculation --entity`
+- `ensureTimeDifferenceCalculation --entity`
 - `ensureConditionalCalculation --entity`
 - `setSummaryToField --element`
 - `ensureConditionalFieldState --entity`
@@ -176,7 +177,8 @@ MetaOps 或再次确认。
 
 完成已验证写入后，modifier 执行完成，但 app-build 请求可能还有其他明确工作。返回已验证的
 `appRoot` 和准确 `formNumber`；通过 `--form-name` 调用时使用返回身份，不再解析 schema。
-完整请求结束后遵循 `{ROOT_DIR}/references/delivery.md`。写后结果无法确认时停止。
+完整或部分交付遵循 `{ROOT_DIR}/references/delivery.md`。写后结果无法确认时，先查明
+受影响表单的状态再继续修改或交付该表单；其他独立验证通过的表单仍需完成交付。
 
 ## 新增分录实体
 

package/skills/cosmic-build/skills/cosmic-meta-modifier/modules/context/SKILL.md

@@ -17,7 +17,7 @@
 ## modifier 特有说明
 
 在执行元数据修改前，确认应用身份已经初始化：
-1. 确认 config.json 中 `_initialized` 为 true
+1. 确认环境凭据可从 `~/.kd/config.json` 解析（见下方 init 入口）
 2. 确认 workspace.json 中 appNumber、bizCloudName、isv 已填充
 3. 若未初始化，按 `cosmic-meta-api/modules/init/SKILL.md` 引导用户补全
 
@@ -29,7 +29,7 @@
 |------|---------------------------|
 | `python` | Windows: `python` / Linux·macOS: `python3` |
 | `cosmic_api` | `SKILL_DIR/../../../cosmic-meta-api/scripts/cosmic_api.py` |
-| `config` | `SKILL_DIR/../../../config.json`（= `skills/config.json`） |
+| `config` | `~/.kd/config.json`（平台级配置，由脚本自行解析） |
 | `field_type_reference` | `SKILL_DIR/../../../cosmic-meta-knowledge/domain-model/field-types.md` |
 | `field_naming_rules` | `SKILL_DIR/../../../cosmic-meta-knowledge/conventions/naming-rules.md` |
 | `basedata_lookup_guide` | `SKILL_DIR/../../../cosmic-meta-knowledge/reference-data/basedata-catalog.md` |

package/skills/cosmic-build/skills/cosmic-meta-modifier/modules/execute/SKILL.md

@@ -10,7 +10,7 @@
 | `cosmic_api` | `SKILL_DIR/../../../cosmic-meta-api/scripts/cosmic_api.py` |
 | `ops_manager` | `SKILL_DIR/../../../cosmic-meta-api/scripts/ops_manager.py` |
 | `pdm_skill` | `SKILL_DIR/../../../cosmic-meta-api/modules/pdm/SKILL.md` |
-| `config` | `SKILL_DIR/../../../config.json`（= `skills/config.json`） |
+| `config` | `~/.kd/config.json`（平台级配置，由脚本自行解析） |
 
 ---
 

package/skills/cosmic-build/skills/cosmic-meta-modifier/modules/operation/SKILL.md

@@ -4,7 +4,7 @@
 静态字段属性归[属性入口](../property/SKILL.md)，字段变化计算和条件界面行为归
 [规则入口](../rule/SKILL.md)。字段必填标记本身不能证明保存或提交时已执行必填检查。
 
-`ROOT_DIR` 是 app-build 提供的 Skill package directory。
+`{ROOT_DIR}` 是 app-build 提供的 Skill package directory。
 
 ## 按当前要求选择契约
 
@@ -19,9 +19,8 @@
 必填/条件必填检查时才使用 `ensureMustInputValidation`，不要为每条自定义条件自动
 追加它。一条提示涉及多个条件时使用一个复合输入；独立要求的多条提示可分别配置。
 
-只要求操作元数据时不创建按钮。需求明确描述用户可见触发入口或交互时，同时包含 UI 事项；
-操作验证后加载界面入口，用返回的 operation key 绑定一个可见控件。仅有操作元数据时不得
-声称按钮已经存在。
+平台或内部操作元数据不创建按钮。面向表单用户手动执行的具名自定义动作直接进入 UI
+`addButton` 闭环，由它创建/复用操作并完成可见绑定。
 
 ## 常用校验
 
@@ -45,6 +44,8 @@ writer 自行绑定目标、检查条件并独立验证写入。只有输入超
 
 复用返回的表单身份与验证结果。全部要求完成后使用根入口统一交付；写入、渲染、
 输出检查按依赖顺序等待。设计态验证与运行态验收分开判断。
+操作定义和可见按钮只证明绑定完成。如果行为依赖尚未实现的插件（包括 `donothing` 操作），
+即使元数据回读通过，业务行为仍应标记待实现。
 
 已有校验通过自身的 `validationId` 定位，不使用规则 ID。
 `extension_required` 不代表授权创建扩展。

package/skills/cosmic-build/skills/cosmic-meta-modifier/modules/operation/operation-write.md

@@ -1,13 +1,17 @@
 ## 边界
 
+菜单项名称、说明属于界面显示对象，不等于操作定义的名称。只修改显示文字时使用
+UI 的 configureDropdownMenu，保留绑定的操作定义。
+
 - 使用调用方已经明确的操作类型。只有平台精确类型未知时，才调用一次
   `listOperationTypes`，由模型选择一个类型；不得把请求识别成 CRUD、审批、
   下推或导航工作流。
 - 一个请求效果只执行一次 `addOperation`、`updateOperation` 或
   `deleteOperation`。用户明确要求多个操作时，执行多个各自独立验证的 CLI；
   不得生成 batch manifest 或执行计划。
-- 只要求操作元数据时不推断按钮、插件或规则。用户明确描述可见触发入口或点击交互时，
-  先完成本操作写入，再复用返回的表单身份与 operation key，进入 UI 的已有操作按钮闭环。
+- 表单用户手动执行的具名自定义业务动作属于可见操作，除非请求明确说明它仅供内部或其他流程调用。
+  此类请求直接进入 UI 的 `addButton` 闭环，由一个命令创建/复用操作并验证可见绑定。
+  平台内置操作和明确的内部操作元数据仍只处理操作本身。
 - 本目录下的 scenarios 和 guides 仅是参考示例，不定义运行时控制流；已知命令
   不读取它们。
 

package/skills/cosmic-build/skills/cosmic-meta-modifier/modules/operation/validation.md

@@ -69,3 +69,5 @@
 命令启用已有
 `MustInputValidation`（包括清除 `SkipMustInput=true`），不存在时才补建，同时保留其他校验。
 只有字段红星而操作校验未启用，不能作为运行态验收证据。
+
+分录最少行数与逐行必填是不同约束。`MustInputValidation` 只校验已有行的必填字段，零行时没有字段可检查，不能证明“至少一行”。已发布操作校验命令没有行数契约时，进入根入口的 Java 操作插件路线，在单据根实体读取准确分录集合并添加提交校验；保持用户指定的操作范围，不把“提交时至少一行”扩大到保存。

package/skills/cosmic-build/skills/cosmic-meta-modifier/modules/property/SKILL.md

@@ -7,11 +7,16 @@ modifier 阶段。
 就是完整必需参数，字段 key 不是前置条件。把这些选择器直接传入命令；只有在线表单中仍存在
 歧义时，命令才返回结构化候选。
 
+`entries` 选择所有非表头实体，包含嵌套子分录。只修改某一个分录，或不同分录中有同名字段时，
+保留准确实体显示名/键，或用限定字段选择器，例如
+`targets.fields:[{entity:"订场明细",field:"单价"}]`。不能用批量别名代替单一分录，
+也不能把“子单据体”等结构类型当作实际实体名称。
+
 用户同时给出准确表单编码和显示名称时，第一次调用就把编码原样传给 `--form-name`，
 不得用显示名称替换或重新解析表单。用户点名表头或分录位置时，在同一次调用的 policy
 目标中保留该位置。
 
-本入口就是 `setProperties` 面向模型的完整公开合同。沿用根交接提供的 `ROOT_DIR`，根据
+本入口就是 `setProperties` 面向模型的完整公开合同。沿用根交接提供的 `{ROOT_DIR}`，根据
 用户给出的字段名和位置编译 policy，并把调用已发布命令作为下一动作；命令自行负责可执行实现
 和在线目标检查。
 
@@ -36,6 +41,11 @@ Windows PowerShell 下需要把内层双引号转义才能到达命令（`'{"A":
 
 ## 高频直达
 
+修改已有字段、控件或分录标识，使用一条
+`renameElementKey --element "<当前名称/Key>" --new-key "<新标识>"`，配合上方表单绑定。
+命令统一补一次开发商前缀，迁移可观察的规则条件/触发字段引用，并验证名称、类型、父级和位置。
+引用清单无法读取时不写入；规则迁移失败时尝试回滚。数据库列名、表名仍是独立标识。
+
 必填、为空提示、静态/设计默认值、显隐、锁定、长度、精度、小数位、标题、布局/样式标量及分录默认行数，
 直接把用户给出的准确字段名和位置编译进对应属性命令。该命令是第一条平台动作，并自行完成
 目标解析、校验和回读；只有结构化未解析结果会给出唯一后续动作。
@@ -69,6 +79,7 @@ archive、表单 Schema 或本地目录。
 | 准确元素的其他高级样式 | 只读一次 `../../../cosmic-meta-knowledge/property-guides/style-properties.md`，再用 `setComplexProperty --complexType style` |
 | 页签上显示的“页签操作” | `ensureTabPageOperations --input '{"tab":"<页签>","items":[{"title":"<显示名称>","operationCode":"<操作编码>","operationType":"<需要新建时的操作类型>","operationName":"<操作名称>"}]}'`；页签项编码 `itemCode` 可省略，命令保留其他页签操作，它不是按钮 |
 | 附件面板行为 | 只读一次 `attachment-panel-properties.md`，再用一次 `setProperties` |
+| 实体权限控制元数据 | `setPermissionControl`，按所需控制查看输入契约；该能力不等同于角色授权或权限项新建 |
 | 其他陌生且已发布的属性 | 只调用一次 `describePropertyInput --propertyNames <名称>`，再执行其返回路由 |
 
 设计器多选字段普通值放 `set`；`MustInputCondition`、`Features`、`CtlTips`、`Style`
@@ -83,12 +94,16 @@ archive、表单 Schema 或本地目录。
 
 实时设计器 Schema 声明只读的 `_Type_`/字段类型和元素类型继续只读。`Key` 不进入批量写入，
 因为批次内改变元素寻址会使后续操作失效。
+字段类型调整属于迁移。任何破坏性替换前，先明确完整目标定义，以及已有数据、字段身份、
+规则、布局和列表引用的保留方式；分别删除和新增成功不能证明迁移完成。
+没有满足这些要求的受支持路径时，保留原字段并报告该项边界，不能先删再试参数。
 `BasedataPropField` 本身只读，不得把这句描述转换成 `Lock:true`。明确设置 `Lock` 时使用
 实时状态（如 `new`/`edit`），不能用布尔值；非法值在认证前拒绝。
-`Lock` 是 FieldAp 表单控件属性。紧凑 policy 自行完成表单树写入和回读，也支持 Lock 与
-其他属性组合；混合写入前先校验全部属性，部分失败返回已完成与待处理项，按回执恢复，
-不重放整个 policy。即使 Property
-Schema 投影显示只读也不需要另找入口。“不可编辑”表示单据全部状态：
+`Lock` 是 FieldAp 表单控件属性。单个表头字段不可编辑时，直接用
+`{"targets":{"fields":["<字段>"],"entities":["header"]},"set":{"Lock":"new,edit,submit,audit"}}`。
+`Lock` 属于 `set`，不能放入 `complex`。紧凑 policy 自行完成表单树写入和回读，即使设计器
+Property Schema 显示只读也不先查询它。混合属性会在写前统一校验；部分失败返回已完成与
+待处理项，按回执恢复，不重放整个 policy。“不可编辑”表示单据全部状态：
 `new,edit,submit,audit`。禁止先查 Schema，也不得改用 `applyFormUi` 或手写 `modifyMeta`。
 
 字段属性（含静态显隐、可编辑性、外观）由本入口处理，属性存储在表单树也不改变归属。

package/skills/cosmic-build/skills/cosmic-meta-modifier/modules/property/complex-apis.md

@@ -36,7 +36,7 @@
 | `mustInputCondition` | setMustInputCondition | 字段级 |
 | `comboItems` | ⛔ ~~setComboItems~~ 已废弃；使用 `quickfield --add-option` / `--remove-option` | 字段级 |
 | `splitTables` | setSplitTables | 实体级 |
-| `dropdownItems` | setDropdownItems | 控件级 |
+| `dropdownItems` | configureDropdownMenu（保留原身份的定向编辑） | 控件级 |
 | `style` | setStyle | 控件级 |
 
 > **使用建议**：上表列出常用的有快捷命令的类型。无快捷命令的类型（如 `userOption`、`billTypePara`、`formVariable`、`freezeList`、`networkControl` 等）使用 `setComplexProperty` 统一入口，完整列表见 `property-reference.md §12`。

package/skills/cosmic-build/skills/cosmic-meta-modifier/modules/property/policy-grammar.md

@@ -59,7 +59,10 @@ policy 会对两个范围内的所有准确同名字段应用同一结果。未
 `FuncType`/`FuncParameter`；当前日期是
 `{"FuncType":"getToday","FuncParameter":"#CurrentDate#"}`，当前日期时间是
 `{"FuncType":"getNow","FuncParameter":"#CurrentDatetime#"}`，当前登录人是
-`{"FuncType":"getCurrentUser","FuncParameter":"#CurrentUser#"}`，只作用于准确点名的 `UserField`。policy 中的引用记录使用
+`{"FuncType":"getCurrentUser","FuncParameter":"#CurrentUser#"}`，只作用于准确点名的 `UserField`。这是设计默认值函数的字段类型边界，不是平台整体能力边界。确认需求要求在 `TextField` 中
+填写当前用户或部门文本时，保留该类型；核对元数据入口后沿原生 Java 表单插件入口继续实现。
+未实施插件属于剩余开发，不能据此宣称无法实现，或仅因 `getCurrentUser` 不适配就建议删表重建。
+policy 中的引用记录使用
 `{"kind":"record","value":"<名称或编码>"}` 或
 `{"kind":"multi-record","values":["<记录>"]}`，统一通过同一 policy。
 `setBasedataDefault` 保留为兼容适配器，新请求使用 policy。城市名称是记录选择器，

package/skills/cosmic-build/skills/cosmic-meta-modifier/modules/report-op/SKILL.md

@@ -145,6 +145,15 @@ artifact 的列差异，绑定到这张报表的每一条菜单，以及有序
 
 ## 直接路径
 
+过滤编辑控件类型与查询比较符是两项能力。当前 `setReportFilters` 输入没有 `fieldType` 或
+`controlType` 选择器。本地核对的平台源码将 `compare=between` 创建为绑定 `DateRangeField` 的
+`FieldAp`，其余为 `TextField`；旧部署可能不同，必须回读实际目标。单日期 `DateField`、
+F7 多选 `MulBaseDataField` 和下拉框 `ComboListField` 需要平台接口扩展。不要声称重建、
+只读类型属性、隐藏列或 Java 查询逻辑能提供这些控件；保留用户要求的界面行为为未解决边界，
+不静默降级为文本框。`getReportSchema` 在证据存在时返回实际 `FieldAp` 与实体 `fieldType`，
+缺少类型证据表示未知，不能推断为 `TextField`。
+
+
 `registerReportPlugin` 直接调用对应命令。CLI 自行解析当前应用内的报表、校验载荷、写入、独立
 读回报表投影并比较请求值。