@shundoo-ai/dsh-cosmic 1.0.21 → 1.0.22

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

@@ -8,6 +8,7 @@ cmd_operations（按钮绑定操作）、cmd_result（后端 NPE 分类）。do_
 from __future__ import annotations
 
 import json
+import difflib
 import os
 import re as _re
 from .cmd_forms import (
@@ -22,13 +23,16 @@ from .cmd_operations import (
     do_get_operation,
     do_list_operations,
 )
-from .cmd_properties import do_get_properties, do_list_elements, do_set_properties
+from .cmd_properties import (
+    do_get_properties, do_get_property_schema, do_list_elements, do_set_properties,
+    _compile_simple_property_map, _resolve_property_declaration, _property_values_equal,
+)
 from .cmd_result import _is_backend_npe
 from .config import _api_call
 from .formatters import _extract_error_message, _is_api_success
 from .mutation_contract import mutation_contract
 
-# ─── 列类型映射常量（单源同步 list_column/compile.py） ────────────────────────
+# ─── Column type mapping constants (single-source sync with list_column/compile.py) ────────────────────────
 
 _LISTCOLUMN_TYPE_MAP = {
     "str": "ListColumnAp",
@@ -58,43 +62,43 @@ _LISTCOLUMN_TYPE_MAP = {
     "map": "ListMapColumnAp",
     "lookup": "ListLookupColumnAp",
 }
-# ─── 引用字段子属性中文名映射 ─────────────────────────────────────────────────
+# ─── Reference field sub-property display name mapping ─────────────────────────────────────────────────
 
 _USER_REF_SUB_NAME_MAP = {
-    "number": "编号",
-    "name": "名称",
-    "code": "编码",
-    "email": "邮箱",
-    "phone": "手机号",
-    "position": "职位",
-    "department": "部门",
-    "org": "组织",
-    "post": "岗位",
-    "gender": "性别",
-    "idNumber": "身份证号",
-    "entryDate": "入职日期",
-    "leaveDate": "离职日期",
+    "number": "Number",
+    "name": "Name",
+    "code": "Code",
+    "email": "Email",
+    "phone": "Phone",
+    "position": "Position",
+    "department": "Department",
+    "org": "Organization",
+    "post": "Post",
+    "gender": "Gender",
+    "idNumber": "ID Number",
+    "entryDate": "Entry Date",
+    "leaveDate": "Leave Date",
 }
 _BASEDATA_REF_SUB_NAME_MAP = {
-    "number": "编号",
-    "name": "名称",
-    "code": "编码",
-    "status": "状态",
-    "description": "描述",
-    "parent": "上级",
-    "level": "级次",
-    "isLeaf": "是否叶子",
-    "enable": "启用",
-    "createDate": "创建日期",
-    "modifyDate": "修改日期",
-    "remark": "备注",
+    "number": "Number",
+    "name": "Name",
+    "code": "Code",
+    "status": "Status",
+    "description": "Description",
+    "parent": "Parent",
+    "level": "Level",
+    "isLeaf": "Is Leaf",
+    "enable": "Enabled",
+    "createDate": "Create Date",
+    "modifyDate": "Modify Date",
+    "remark": "Remark",
 }
 def _lookup_field_meta(elements_data, field_key, log_tag):
-    """按准确 key 优先、再按唯一显示名定位字段元信息。
+    """按准确 key 优先、再按唯一显示名定位字段元信息。.
 
-    先精确匹配 field_key；未命中时按平台固定长度前缀截断（fieldKey>21 截尾）
-    做最长前缀回退，回读平台真实 key。返回 (field_meta_or_None, resolved_field_key)，
-    resolved_field_key 为回退后的平台真实 key（无回退时即原值）。
+    先精确匹配 field_key; No match时按平台固定长度前缀截断 (fieldKey>21 截尾)
+    做最长前缀回退, 回读平台真实 key. 返回 (field_meta_or_None, resolved_field_key),
+    resolved_field_key 为回退后的平台真实 key (无回退时即原值) .
     """
     for el in elements_data:
         if el.get("key") == field_key:
@@ -115,8 +119,8 @@ def _lookup_field_meta(elements_data, field_key, log_tag):
     )
     if truncated:
         print(
-            f"[{log_tag}] 字段 '{field_key}' 未精确命中，"
-            f"回退到平台真实 key '{truncated}'（平台静默截断）",
+            f"[{log_tag}] Field '{field_key}' 未精确命中, "
+            f"回退 to 平台真实 key '{truncated}' (平台静默截断) ",
             flush=True,
         )
         for el in elements_data:
@@ -142,13 +146,13 @@ def do_add_list_column(cfg, token, form_number, field_key, name=None,
                        column_type=None, column_key=None,
                        hyperlink=False, order="NotOrder",
                        after_column=None, visible=True):
-    """快捷在列表视图添加一列（form+listcolumn+add）。
+    """快捷在列表视图添加一列 (form+listcolumn+add) .
 
-    - 自动解析 formNumber → formId
-    - 自动查字段类型并映射 columnType（DecimalField → DecimalListColumnAp 等）
-    - 自动取字段 name 作为列名（可用 --name 覆盖）
-    - column_key 缺省为 `listcol_{field_key}`
-    - 自动探测列表是否已存在同 listFieldId 的列，存在则报错（防重复）
+    - Auto-resolve formNumber → formId
+    - 自动查Field type并映射 columnType (DecimalField → DecimalListColumnAp 等)
+    - 自动取Field name 作为列名 (可用 --name 覆盖)
+    - column_key defaults to `listcol_{field_key}`
+    - 自动探测列表是否Already exists同 listFieldId 的列, 存在则报错 (防重复)
 
     Returns:
         (form_id, [op])
@@ -157,45 +161,45 @@ def do_add_list_column(cfg, token, form_number, field_key, name=None,
     form_id = _resolve_form_id(cfg, token, form_number)
     print(f"[addListColumn] formNumber={form_number} → formId={form_id}", flush=True)
 
-    # 2. 查询字段列表，定位目标字段类型（用于自动映射 columnType / 回填 name）
+    # 2. 查询Field列表, 定位目标Field type (用于自动映射 columnType / 回填 name)
     elements_result = do_list_elements(cfg, token, form_number, category="field")
     if not _is_api_success(elements_result):
-        raise ValueError(f"查询字段列表失败: {_extract_error_message(elements_result)}")
+        raise ValueError(f"查询Field列表failed: {_extract_error_message(elements_result)}")
     elements_data = elements_result.get("data") or []
     field_meta, field_key = _lookup_field_meta(elements_data, field_key, "addListColumn")
     if field_meta is None:
         raise ValueError(
-            f"表单 '{form_number}' 中未找到字段 key='{field_key}'；请先确认字段已存在或先 addField"
+            f"Form '{form_number}' 中未找 to Field key='{field_key}'; 请先确认FieldAlready exists或先 addField"
         )
 
     field_type = field_meta.get("type") or ""
     default_name = field_meta.get("name") or field_key
 
-    # 3. 推导 columnType（用户显式传入优先）
+    # 3. 推导 columnType (用户显式传入优先)
     resolved_column_type = column_type or _LISTCOLUMN_TYPE_MAP.get(field_type, "ListColumnAp")
     if column_type is None:
         print(
-            f"[addListColumn] 字段 '{field_key}' 类型 '{field_type}' → columnType={resolved_column_type}",
+            f"[addListColumn] Field '{field_key}' type '{field_type}' → columnType={resolved_column_type}",
             flush=True,
         )
 
-    # 4. 防重复：检查列表是否已有同 listFieldId 的列
+    # 4. 防重复: 检查列表是否已有同 listFieldId 的列
     try:
         schema_result = do_get_form_schema(cfg, token, form_id)
         list_columns = ((schema_result.get("data") or {}).get("listColumns")) or []
         for col in list_columns:
             if col.get("listFieldId") == field_key:
                 raise ValueError(
-                    f"列表已存在绑定字段 '{field_key}' 的列 (key='{col.get('key')}', name='{col.get('name')}')；"
-                    f"如需修改请用 modify，禁止重复 add"
+                    f"列表Already exists绑定Field '{field_key}'  column (key='{col.get('key')}', name='{col.get('name')}'); "
+                    f"如需修改请用 modify, 禁止重复 add"
                 )
     except ValueError:
         raise
     except Exception as e:
-        # schema 查询失败不阻塞（服务端会兜底校验），仅告警
-        print(f"[addListColumn] ⚠️ 预检 listColumns 异常: {e}（继续执行，由服务端兜底校验）", flush=True)
+        # schema 查询failed不阻塞 (服务端会兜底校验) , 仅告警
+        print(f"[addListColumn] ⚠️ Pre-check listColumns exception: {e} (继续执行, 由服务端兜底校验) ", flush=True)
 
-    # 5. 构造 op
+    # 5. Build op
     resolved_key = column_key or f"listcol_{field_key}"
     resolved_name = name or default_name
 
@@ -206,7 +210,7 @@ def do_add_list_column(cfg, token, form_number, field_key, name=None,
         "hyperlink": bool(hyperlink),
         "order": order,
     }
-    # visible 仅当 hidden=True 时显式写入 false（默认可见，无需传）
+    # visible 仅当 hidden=True 时显式写入 false (default可见, 无需传)
     if not visible:
         value["visible"] = False
     op = {
@@ -222,13 +226,13 @@ def do_add_list_column(cfg, token, form_number, field_key, name=None,
         op["extra"] = {"afterField": after_column}
 
     return form_id, [op]
-# ─── addButton 快捷命令（加按钮 + 绑定操作 一条命令）─────────────────
+# ─── addButton 快捷命令 (加Button + 绑定操作 一条命令) ─────────────────
 
 def _find_control_in_form_layout(form_layout, target_key):
-    """在 formLayout 树里递归查找 key == target_key 的节点。
+    """在 formLayout 树里递归查找 key == target_key 的节点.
 
-    返回 (node, parent_key) 或 None；命中时 parent_key 可能为 None（根节点下直挂）。
-    用于 addButton / addWidget 的前置查重，避免服务端 add 非幂等导致的重复记录。
+    返回 (node, parent_key) 或 None; 命中时 parent_key 可能为 None (根节点下直挂) .
+    用于 addButton / addWidget 的前置查重, 避免服务端 add 非幂等导致的重复记录.
     """
     if not isinstance(form_layout, dict):
         return None
@@ -246,14 +250,14 @@ def _find_control_in_form_layout(form_layout, target_key):
 
     return _walk(form_layout, None)
 def _detect_list_toolbar_key(schema_result):
-    """在 getFormSchema 返回中探测 listLayout 顶层 ToolbarAp 的 key。
+    """在 getFormSchema 返回中探测 listLayout 顶层 ToolbarAp 的 key.
 
-    兼容两种苍穹列表模板：
-      - 新式：listLayout.children 里含 key=tbmain, type=ToolbarAp
-      - 旧式：listLayout.children 里含 key=_toolbar_, type=ToolbarAp（单据/基础资料模板常见）
+    兼容两种苍穹列表模板:
+      - 新式: listLayout.children 里含 key=tbmain, type=ToolbarAp
+      - 旧式: listLayout.children 里含 key=_toolbar_, type=ToolbarAp (单据/基础资料模板常见)
 
-    返回首个命中的 key；未命中返回 None。
-    供 do_add_button 在 target_view=list 且未显式 parentScope 时自动挂载容器定位。
+    返回首个命中的 key; No match返回 None.
+    供 do_add_button 在 target_view=list 且未显式 parentScope 时自动挂载容器定位.
     """
     if not isinstance(schema_result, dict):
         return None
@@ -270,13 +274,15 @@ def _detect_list_toolbar_key(schema_result):
     return None
 
 def _platform_element_key(element_key):
-    """返回平台实际存储的大小写形式的元素 key。
-
-    平台在写入时会把元素 key 转为小写。addButton 原先用调用方给的大小写写入按钮，
-    随后又用同样的大小写调 setProperties(OperationKey)，而平台里存的是
-    bar_oa_callphone，于是查找报「未找到元素」，留下一个已创建但没绑定任何操作
-    （OperationKey 为空）的孤儿按钮，命令本身还报失败。写入与后续绑定必须用同一个
-    存储形式的名字。
+    """Return the element key in the casing the platform actually stores.
+
+    The platform lower-cases element keys on write. addButton used to write the
+    button with the caller's casing and then call setProperties(OperationKey)
+    with that same casing, which the platform could not resolve: it had stored
+    bar_oa_callphone while the CLI asked for bar_oa_callPhone. The button was
+    created and left bound to nothing (OperationKey null), and the command
+    reported failure while leaving that orphan behind. Deriving the key in the
+    stored casing keeps the write and the follow-up binding on the same name.
     """
     if not isinstance(element_key, str):
         return element_key
@@ -284,7 +290,7 @@ def _platform_element_key(element_key):
 
 
 def _resolve_button_operation_key(operations, selector):
-    """解析一个已有操作 key/显示名；无匹配时保留为新语义 key。"""
+    """Resolve one existing operation key/name, or preserve a new semantic key."""
     wanted = str(selector or "").strip()
     rows = operations if isinstance(operations, list) else []
     key_matches = [
@@ -316,15 +322,17 @@ def do_add_button(cfg, token, form_number, name, operation_key,
                   index=None, log_enable=True, skip_operation=False,
                   target_view=None, template_number=None,
                   verified_target=None):
-    """一条命令完成加按钮+绑定操作（编排 addOperation + modifyMeta(add) + setProperties(OperationKey)）。
+    """一条命令completed加Button+绑定操作 (编排 addOperation + modifyMeta(add  ) + setProperties(OperationKey)) .
 
-    返回：dict（success/formId/modelType/buttonType/buttonKey/parentScope/operationKey/modifyMeta/setProperties）
+    返回: dict (success/formId/modelType/buttonType/buttonKey/parentScope/operationKey/modifyMeta/setProperties)
     """
     # 延迟导入：do_modify_meta 在 cmd_metaops（上层），模块级互相 import 会成环。
     from .cmd_metaops import do_modify_meta
-    # 平台以小写存储 operationKey，因此在用它派生按钮 key、绑定操作和断言操作存在之前
-    # 先把身份解析成存储形式。否则绑定混合大小写的 key 会得到一个没绑上操作的按钮，
-    # 而 operationPresent 检查永远不可能通过。
+    # The platform stores operationKey lower-cased, so resolve the identity to
+    # the stored casing before it is used to derive the button key, to bind the
+    # operation and to assert the operation exists. Without this, binding a
+    # mixed-case key produced a button bound to nothing and an operationPresent
+    # check that could never succeed.
     operations_result = None
     raw_operation_selector = str(operation_key or "").strip()
     if _re.fullmatch(r"[A-Za-z0-9_.-]+", raw_operation_selector):
@@ -337,22 +345,23 @@ def do_add_button(cfg, token, form_number, name, operation_key,
         if isinstance(operations_data, dict):
             operations_data = operations_data.get("operations") or []
         operation_key = _resolve_button_operation_key(operations_data, raw_operation_selector)
-    # 标准化 target_view
+    # Normalize target_view
     tv = (target_view or "form").strip().lower()
     if tv not in ("form", "list"):
-        raise ValueError(f"target_view 只支持 'form' 或 'list'，当前值={target_view}")
-    # 公开写命令复用 CLI 已证明的精确表单/应用元组；仅内部调用保留回退。
+        raise ValueError(f"target_view 只支持 'form' 或 'list', Current value={target_view}")
+    # Public writes pass the exact form/app tuple already proved by the CLI.
+    # The fallback remains only for internal callers.
     form_rec = verified_target
     if form_rec is None:
         forms_result = do_query_forms(cfg, token, keyword=form_number)
         if not _is_api_success(forms_result):
-            raise ValueError(f"查询表单失败: {_extract_error_message(forms_result)}")
+            raise ValueError(f"查询Formfailed: {_extract_error_message(forms_result)}")
         for f in (forms_result.get("data") or []):
             if f.get("formNumber") == form_number:
                 form_rec = f
                 break
     if not form_rec:
-        raise ValueError(f"未找到编码为 '{form_number}' 的表单")
+        raise ValueError(f"未找 to Code为 '{form_number}'  form")
     form_id = form_rec.get("formId")
     model_type = form_rec.get("modelType") or ""
     # Ported from beta 0b495ae1: the dialog template puts its buttons in a different
@@ -362,19 +371,19 @@ def do_add_button(cfg, token, form_number, name, operation_key,
     print(f"[addButton] formNumber={form_number} → formId={form_id}, modelType={model_type}",
           flush=True)
 
-    # 2. 判定按钮承载方式（button_type 显式传入优先）
+    # 2. 判定Button承载方式 (button_type 显式传入优先)
     bar_types = {"BillFormModel", "BaseFormModel"}
     dyn_types = {"DynamicFormModel", "ReportFormModel", "PrintModel",
                  "ParameterFormModel", "QingAnalysisModel"}
     if tv == "list":
-        # 列表视图 tbmain 下只有 BarItemAp，强制 BarItem；仅 BillFormModel / BaseFormModel 具备 listMeta
+        # 列表视图 tbmain 下只有 BarItemAp, 强制 BarItem; 仅 BillFormModel / BaseFormModel 具备 listMeta
         if model_type not in bar_types:
             raise ValueError(
-                f"target_view=list 仅支持 BillFormModel / BaseFormModel，"
-                f"当前 modelType={model_type} 无 listMeta"
+                f"target_view=list 仅支持 BillFormModel / BaseFormModel, "
+                f"当前 modelType={model_type} no listMeta"
             )
         if button_type and button_type != "BarItem":
-            print(f"[addButton] ⚠️ target_view=list 时 button_type 强制为 BarItem（传入={button_type} 忽略）",
+            print(f"[addButton] ⚠️ target_view=list 时 button_type 强制为 BarItem (传入={button_type} 忽略) ",
                   flush=True)
         bt = "BarItem"
     elif button_type:
@@ -385,9 +394,9 @@ def do_add_button(cfg, token, form_number, name, operation_key,
         bt = "ButtonAp"
     else:
         bt = "BarItem"
-        print(f"[addButton] ⚠️ 未识别 modelType={model_type}，默认使用 BarItem", flush=True)
+        print(f"[addButton] ⚠️ Unrecognized modelType={model_type}, default使用 BarItem", flush=True)
 
-    # 3. 生成按钮 key & parentScope
+    # 3. Generate button key & parentScope
     if key:
         btn_key = key
     elif bt == "BarItem":
@@ -400,18 +409,18 @@ def do_add_button(cfg, token, form_number, name, operation_key,
         scope = parent_scope
         schema_cached = None
     elif bt == "BarItem" and tv == "list":
-        # 列表工具栏容器自动探测：兼容 tbmain / _toolbar_ 两种模板。
+        # 列表工具栏容器自动探测: 兼容 tbmain / _toolbar_ 两种模板.
         schema_cached = do_get_form_schema(cfg, token, form_id)
         detected = _detect_list_toolbar_key(schema_cached)
         if detected:
             scope = detected
             if detected != "tbmain":
-                print(f"[addButton] ℹ️ 自动探测到列表工具栏容器 key={detected}（旧式模板），已替代默认 tbmain",
+                print(f"[addButton] ℹ️ 自动探测 to 列表工具栏容器 key={detected} (旧式模板) , 已替代default tbmain",
                       flush=True)
         else:
             scope = "tbmain"
-            print(f"[addButton] ⚠️ 未在 listLayout 顶层找到 ToolbarAp 子节点，回退 parentScope=tbmain；"
-                  f"若落位异常请手动 --parentScope 指定真实容器 key", flush=True)
+            print(f"[addButton] ⚠️ 未在 listLayout 顶层Found ToolbarAp 子节点, 回退 parentScope=tbmain; "
+                  f"If positioning is wrong, manually specify real container key via --parentScope", flush=True)
     elif bt == "BarItem":
         scope = "tbmain"
         schema_cached = None
@@ -420,20 +429,21 @@ def do_add_button(cfg, token, form_number, name, operation_key,
         schema_cached = None
     elif bt == "AdvConBarItem":
         raise ValueError(
-            "AdvConBarItem（分录工具栏按钮）必须通过 --parentScope 显式指定分录工具栏 key，"
-            "请先用 ui_api.py getToolbars 获取"
+            "AdvConBarItem (分录工具栏Button) 必须通过 --parentScope 显式指定分录工具栏 key, "
+            "please use ui_api.py getToolbars to get it first"
         )
     else:
-        scope = form_number  # ButtonAp/Button 直挂表单根
+        scope = form_number  # ButtonAp/Button 直挂Form根
         schema_cached = None
 
-    # 4. 在创建操作之前检查非幂等的按钮写入。
+    # 4. Check the non-idempotent button write before creating an operation.
     schema_result = schema_cached if schema_cached is not None else do_get_form_schema(cfg, token, form_id)
     button_already_exists = False
     existing_operation_key = None
     if not _is_api_success(schema_result):
         raise ValueError(
-            "BUTTON_LAYOUT_INVENTORY_UNAVAILABLE: 无法在非幂等按钮写入前验证布局"
+            "BUTTON_LAYOUT_INVENTORY_UNAVAILABLE: cannot verify the target layout "
+            "before a non-idempotent button write"
         )
     schema_data = schema_result.get("data") or {}
     layout_key = "listLayout" if tv == "list" else "formLayout"
@@ -443,8 +453,8 @@ def do_add_button(cfg, token, form_number, name, operation_key,
         _existing_node, _existing_parent = hit
         if _existing_parent != scope:
             raise ValueError(
-                f"BUTTON_PARENT_MISMATCH: 已有按钮 {btn_key} 位于 "
-                f"{_existing_parent!r}，请求的 parentScope={scope!r}"
+                f"BUTTON_PARENT_MISMATCH: existing button {btn_key} is under "
+                f"{_existing_parent!r}, requested parentScope={scope!r}"
             )
         button_already_exists = True
         existing_operation_key = (
@@ -454,13 +464,17 @@ def do_add_button(cfg, token, form_number, name, operation_key,
     full_metadata = do_load_full_metadata(cfg, token, form_number)
     if not _is_api_success(full_metadata):
         raise ValueError(
-            "BUTTON_KEY_INVENTORY_UNAVAILABLE: 无法读取完整元数据，未写入按钮或操作"
+            "BUTTON_KEY_INVENTORY_UNAVAILABLE: full metadata cannot be read; "
+            "no button or operation was written"
         )
     published_type = _find_element_type_by_key(
         (full_metadata or {}).get("data"), btn_key
     )
-    # 单据表单与列表共享同一元数据命名空间。默认 bar_<operationKey> 已被表单
-    # 工具栏占用时，为列表使用确定性的 tbl_ 前缀，避免与表单按钮冲突。
+    # A Bill form and its list share one metadata namespace.  The historical
+    # default ``bar_<operationKey>`` therefore collides when callers publish the
+    # same semantic operation on both toolbars.  Keep the legacy key when it is
+    # free, but choose a deterministic list-only key when the implicit key is
+    # already owned by the form layout.
     if (
         published_type is not None
         and not button_already_exists
@@ -473,8 +487,8 @@ def do_add_button(cfg, token, form_number, name, operation_key,
             _existing_node, _existing_parent = fallback_hit
             if _existing_parent != scope:
                 raise ValueError(
-                    f"BUTTON_PARENT_MISMATCH: 已有按钮 {btn_key} 位于 "
-                    f"{_existing_parent!r}，请求的 parentScope={scope!r}"
+                    f"BUTTON_PARENT_MISMATCH: existing button {btn_key} is under "
+                    f"{_existing_parent!r}, requested parentScope={scope!r}"
                 )
             button_already_exists = True
             existing_operation_key = (
@@ -486,28 +500,31 @@ def do_add_button(cfg, token, form_number, name, operation_key,
         )
     if published_type is not None and not button_already_exists:
         raise ValueError(
-            f"BUTTON_KEY_ALREADY_USED: key {btn_key!r} 已发布为 "
-            f"{published_type!r}，未写入按钮或操作"
+            f"BUTTON_KEY_ALREADY_USED: key {btn_key!r} is already published as "
+            f"{published_type!r}; no button or operation was written"
         )
 
-    # T_META_ENTITY.FKey 是 character varying(36)，按钮 key 与操作 key 共用这个上限。
-    # addButton 会用操作 key 派生按钮 key（bar_/tbl_/btn 前缀），所以一个本身合法的
-    # operationKey 仍可能派生出超长的按钮 key。数据库层失败会留下一条存不下去的记录，
-    # 之后这张表单的所有元数据写入都会被它永久卡死。
-    # 这段刻意放在 skip_operation 分支之前：--skipOperation 只跳过操作写入，
-    # 从不跳过按钮写入，因此也不能跳过这项检查。
+    # T_META_ENTITY.FKey is character varying(36) and stores button keys as well
+    # as operation keys. addButton derives the button key from the operation key
+    # ("bar_"/"tbl_"/"btn"/"tbl_" prefix), so an operationKey that is itself
+    # legal can still produce an over-long button key. A DB-level failure leaves
+    # an unsavable row that bricks every later metadata write on the form.
+    # This sits before the skip_operation branch on purpose: --skipOperation
+    # skips only the operation write, never the button write, so it must not
+    # skip this check either.
     if len(btn_key) > _OPERATION_KEY_MAX_LENGTH:
         raise ValueError(
-            "BUTTON_KEY_TOO_LONG: 派生出的按钮 key "
-            f"{btn_key!r} 长度为 {len(btn_key)}，超过平台存储上限 "
-            f"{_OPERATION_KEY_MAX_LENGTH}；请缩短 operationKey 或显式传入更短的 --key"
+            "BUTTON_KEY_TOO_LONG: derived button key "
+            f"{btn_key!r} is {len(btn_key)} characters, exceeding the "
+            f"platform storage limit of {_OPERATION_KEY_MAX_LENGTH}; "
+            "shorten operationKey or pass an explicit shorter --key"
         )
 
-    # 5. operationKey 预检 → 必要时 addOperation
+    # 5. operationKey pre-check → addOperation if needed
     added_operation = False
     if skip_operation:
-        print(f"[addButton] --skipOperation 指定，跳过 addOperation"
-              f"（需确保 operationKey={operation_key} 已存在）", flush=True)
+        print(f"[addButton] --skipOperation 指定, 跳过 addOperation"
+              f" (must ensure operationKey={operation_key} Already exists) ", flush=True)
     else:
         ops_result = operations_result or do_list_operations(cfg, token, form_number)
         ops_data = ops_result.get("data") if _is_api_success(ops_result) else None
@@ -519,8 +536,10 @@ def do_add_button(cfg, token, form_number, name, operation_key,
             existing = []
         existing_keys = {o.get("operationKey") for o in existing if isinstance(o, dict)}
         operation_exists = operation_key in existing_keys
-        # listOperations 在 addOperation 后可能短暂滞后。一次精确回读避免把只绑定
-        # 既有操作的请求误判成需要重复创建。
+
+        # listOperations can lag immediately after addOperation.  One exact read
+        # prevents a stale inventory from turning a bind-only request into a
+        # duplicate operation write.
         if not operation_exists:
             exact_operation = do_get_operation(
                 cfg, token, form_number, operation_key
@@ -536,7 +555,7 @@ def do_add_button(cfg, token, form_number, name, operation_key,
                 and exact_data.get("operationKey") == operation_key
             )
         if operation_exists:
-            print(f"[addButton] operationKey={operation_key} 已存在，跳过 addOperation",
+            print(f"[addButton] operationKey={operation_key} Already exists, 跳过 addOperation",
                   flush=True)
         else:
             op_config = {
@@ -547,8 +566,8 @@ def do_add_button(cfg, token, form_number, name, operation_key,
             }
             add_op_result = do_add_operation(cfg, token, form_number, op_config)
             if not _is_api_success(add_op_result):
-                # 已知后端 addOperation NPE 缺陷：响应抛 NPE 但实际已写入。
-                # 通过 listOperations 后置回查，operationKey 已存在则视为成功。
+                # 已知后端 addOperation NPE 缺陷: 响应抛 NPE 但实际written.
+                # 通过 listOperations 后置回查, operationKey Already exists则视为succeeded.
                 err_msg = _extract_error_message(add_op_result) or ""
                 looks_like_npe = _is_backend_npe(err_msg)
                 recovered = False
@@ -567,8 +586,8 @@ def do_add_button(cfg, token, form_number, name, operation_key,
                             recovered = True
                             added_operation = True
                             print(
-                                f"[addButton] ⚠️ addOperation 响应 NPE，但回查 listOperations "
-                                f"已存在 operationKey={operation_key}，视为已写入（已知后端缺陷容忍）",
+                                f"[addButton] ⚠️ addOperation 响应 NPE, 但回查 listOperations "
+                                f"Already exists operationKey={operation_key}, 视为written (已知后端缺陷容忍) ",
                                 flush=True,
                             )
                 if not recovered and "操作Key已存在" in err_msg:
@@ -587,18 +606,18 @@ def do_add_button(cfg, token, form_number, name, operation_key,
                     ):
                         recovered = True
                         print(
-                            f"[addButton] operationKey={operation_key} 已由精确回读确认存在，"
+                            f"[addButton] operationKey={operation_key} 已由精确回读确认存在, "
                             "按绑定既有操作继续",
                             flush=True,
                         )
                 if not recovered:
-                    raise ValueError(f"addOperation 失败: {err_msg}")
+                    raise ValueError(f"addOperation failed: {err_msg}")
             else:
                 added_operation = True
-                print(f"[addButton] ✅ 新建操作 {operation_key} "
+                print(f"[addButton] ✅ New operation {operation_key} "
                       f"(operationType={operation_type})", flush=True)
 
-    # 6. modifyMeta 加按钮/widget
+    # 6. modifyMeta 加Button/widget
     if tv == "list":
         value = {"controlType": "BarItemAp", "buttonType": bt, "name": name, "operationKey": operation_key}
         element_type = "listbutton"
@@ -636,8 +655,8 @@ def do_add_button(cfg, token, form_number, name, operation_key,
                                        form_number=form_number)
         mm = modify_result.get("modifyMeta") if isinstance(modify_result, dict) else None
         if mm is not None and not _is_api_success(mm):
-            # 已知后端 modifyMeta NPE 缺陷：响应抛 NPE 但实际已写入。
-            # 回查 form layout，若 btn_key 已出现在 parent 下则视为成功。
+            # 已知后端 modifyMeta NPE 缺陷: 响应抛 NPE 但实际written.
+            # 回查 form layout, 若 btn_key 已出现在 parent 下则视为succeeded.
             err_msg = _extract_error_message(mm) or ""
             looks_like_npe = _is_backend_npe(err_msg)
             recovered = False
@@ -650,30 +669,30 @@ def do_add_button(cfg, token, form_number, name, operation_key,
                     if _find_control_in_form_layout(layout_tree, btn_key) is not None:
                         recovered = True
                         print(
-                            f"[addButton] ⚠️ modifyMeta(add {element_type}) 响应 NPE，但回查 "
-                            f"{layout_key} 已找到 {btn_key}，视为已写入（已知后端缺陷容忍）",
+                            f"[addButton] ⚠️ modifyMeta(add   {element_type}) 响应 NPE, 但回查 "
+                            f"{layout_key} 已Found {btn_key}, 视为written (已知后端缺陷容忍) ",
                             flush=True,
                         )
             if not recovered:
                 raise ValueError(
-                    f"modifyMeta(add {element_type}) 失败: {err_msg}"
+                    f"modifyMeta(add   {element_type}) failed: {err_msg}"
                 )
         else:
-            print(f"[addButton] ✅ 按钮 {btn_key} ({element_type}/{bt}) 已挂到 parentScope={scope}",
+            print(f"[addButton] ✅ Button {btn_key} ({element_type}/{bt}) 已挂 to  parentScope={scope}",
                   flush=True)
 
-    # 7. setProperties 绑定 OperationKey
+    # 7. setProperties bind OperationKey
     if tv == "list":
         bind_result = {
             "skipped": True,
-            "reason": "target_view=list：operationKey 已随 add op 的 value 直接绑定在 BarItemAp 上",
+            "reason": "target_view=list: operationKey 已随 add op 的 value 直接绑定在 BarItemAp 上",
         }
-        print(f"[addButton] ✅ target_view=list 绑定 OperationKey={operation_key} → {btn_key} (随 add op 完成)",
+        print(f"[addButton] ✅ target_view=list Bind OperationKey={operation_key} → {btn_key} (随 add op completed)",
               flush=True)
     elif button_already_exists and existing_operation_key == operation_key:
         bind_result = {
             "skipped": True,
-            "reason": "已有按钮已经绑定请求的 OperationKey",
+            "reason": "existing button already has the requested OperationKey",
         }
     else:
         bind_result = do_set_properties(
@@ -684,11 +703,12 @@ def do_add_button(cfg, token, form_number, name, operation_key,
         )
         if not _is_api_success(bind_result):
             raise ValueError(
-                f"setProperties(OperationKey) 失败: {_extract_error_message(bind_result)}"
+                f"setProperties(OperationKey) failed: {_extract_error_message(bind_result)}"
             )
-        print(f"[addButton] ✅ 绑定 OperationKey={operation_key} → {btn_key}", flush=True)
+        print(f"[addButton] ✅ Bind OperationKey={operation_key} → {btn_key}", flush=True)
 
-    # 8. 独立终态回读；后端成功回执不能证明 UI 写入没有被静默跳过。
+    # 8. One independent final read proves the complete closure.  This backend
+    # can return success while silently skipping a UI write.
     verify_schema = do_get_form_schema(cfg, token, form_id)
     verify_layout = ((verify_schema.get("data") or {}).get(
         "listLayout" if tv == "list" else "formLayout"
@@ -736,7 +756,7 @@ def do_add_button(cfg, token, form_number, name, operation_key,
         return {
             "status": False,
             "errorCode": "ADD_BUTTON_VERIFY_FAILED",
-            "message": "按钮闭环未通过独立元数据回读",
+            "message": "button closure did not pass independent metadata read-back",
             "data": verification,
         }
 
@@ -754,31 +774,31 @@ def do_add_button(cfg, token, form_number, name, operation_key,
         "setProperties": bind_result,
         "verification": verification,
     }
-# ─── 过滤字段 / 工具栏项 CLI （listMeta子项，配合 FilterColumnHandler）────
+# ─── 过滤Field / 工具栏项 CLI  (listMeta子项, 配合 FilterColumnHandler) ────
 
 # 视图 key → elementType
-# ⚠️ 服务端真正识别的 parentScope ID 为【无 ap 后缀】版本。带 ap 后缀的旧值仅作兼容，
-#   统一通过 FILTER_VIEW_ALIAS 规范化为无 ap 后缀版。
+# ⚠️ 服务端真正识别的 parentScope ID 为【无 ap 后缀】版本. 带 ap 后缀的旧值仅作兼容,
+#   统一通过 FILTER_VIEW_ALIAS 规范化为无 ap 后缀版.
 FILTER_VIEW_PARENT_KEYS = {
-    # 规范值（服务端真正识别）
-    "filtergridview":       "commonfiltercolumn",    # 常用过滤
-    "schemefilterview":     "schemefiltercolumn",    # 方案过滤
-    "fastsearchgridview":   "commonfiltercolumn",    # 快捷搜索
-    # 旧别名（向后兼容；内部统一映射到无 ap 后缀版）
+    # 规范值 (服务端真正识别)
+    "filtergridview":       "commonfiltercolumn",    # Common filter
+    "schemefilterview":     "schemefiltercolumn",    # Scheme filter
+    "fastsearchgridview":   "commonfiltercolumn",    # Quick search
+    # 旧别名 (向后兼容; 内部统一映射 to 无 ap 后缀版)
     "filtergridviewap":     "commonfiltercolumn",
     "schemefilterviewap":   "schemefiltercolumn",
     "fastsearchgridviewap": "commonfiltercolumn",
 }
-# 旧别名 → 服务端规范值（用于内部强制规范化）
+# 旧别名 → 服务端规范值 (用于内部强制规范化)
 FILTER_VIEW_ALIAS = {
     "filtergridviewap":     "filtergridview",
     "schemefilterviewap":   "schemefilterview",
     "fastsearchgridviewap": "fastsearchgridview",
 }
 def _normalize_filter_parent_scope(parent_scope):
-    """把带 ap 后缀的旧 parentScope 规范化为服务端真正识别的无 ap 后缀版。"""
+    """把带 ap 后缀的旧 parentScope 规范化为服务端真正识别的无 ap 后缀版. """
     return FILTER_VIEW_ALIAS.get(parent_scope, parent_scope)
-# 按 FieldType 推导 Common* 子类（与服务端 inferControlType 规则一致）
+# 按 FieldType 推导 Common* 子类 (与服务端 inferControlType 规则一致)
 _COMMON_FILTER_TYPE_MAP = {
     "DateField":          "CommonDateFilterColumnAp",
     "DateTimeField":      "CommonDateFilterColumnAp",
@@ -804,32 +824,32 @@ _COMMON_FILTER_TYPE_MAP = {
     "CheckBoxField":      "CommonCheckBoxFilterColumnAp",
     "BooleanField":       "CommonCheckBoxFilterColumnAp",
 }
-# 引用属性子 key → 中文显示名映射
+# 引用属性子 key → 中文Display名映射
 _USER_REF_SUB_NAME_MAP = {
-    "number":      "工号",
-    "name":        "姓名",
-    "phone":       "电话",
-    "email":       "邮箱",
-    "department":  "部门",
-    "position":    "职务",
+    "number":      "Employee ID",
+    "name":        "Full Name",
+    "phone":       "Phone",
+    "email":       "Email",
+    "department":  "Department",
+    "position":    "Position",
     "id":          "ID",
-    "picturefield":"头像",
+    "picturefield":"Avatar",
 }
 _BASEDATA_REF_SUB_NAME_MAP = {
-    "number":      "编号",
-    "name":        "名称",
-    "description": "描述",
+    "number":      "Number",
+    "name":        "Name",
+    "description": "Description",
     "id":          "ID",
 }
 _USER_FIELD_TYPES = {"UserField", "CreaterField", "ModifierField", "AuditorField"}
 def _derive_ref_prop_sub_name(parent_field_type, sub_key):
-    """按父字段类型返回子属性的中文显示名，未命中则返回原 sub_key。"""
+    """按父Field type返回子属性的中文Display名, No match则返回原 sub_key. """
     if not sub_key:
         return sub_key
     if parent_field_type in _USER_FIELD_TYPES:
         return _USER_REF_SUB_NAME_MAP.get(sub_key, sub_key)
     return _BASEDATA_REF_SUB_NAME_MAP.get(sub_key, sub_key)
-# 按 FieldType 推导 Scheme* 子类
+# Derive Scheme* subclass by FieldType
 _SCHEME_FILTER_TYPE_MAP = {
     "DateField":          "SchemeDateFilterColumnAp",
     "DateTimeField":      "SchemeDateFilterColumnAp",
@@ -855,7 +875,7 @@ _SCHEME_FILTER_TYPE_MAP = {
 }
 def do_can_add_filter_column(cfg, token, form_number, parent_scope,
                               control_type=None, field_name=None, element_type=None):
-    """过滤字段添加预校验。调用服务端 FilterColumnHandler.canAddFilterColumn。
+    """过滤Field添加预校验. 调用服务端 FilterColumnHandler.canAddFilterColumn.
 
     Returns:
         dict: { allowed: bool, reason?: str }
@@ -870,8 +890,8 @@ def do_can_add_filter_column(cfg, token, form_number, parent_scope,
 def do_list_asst_types(cfg, token, form_number=None, element_key=None):
     """List assistant data categories globally or for an existing field context.
 
-    不传目标时返回全局类别目录，供新建 AssistantField；同时传 formNumber 和
-    elementKey 时保留字段上下文的上级类别过滤。
+    With no target it returns the global category catalog for AssistantField creation.
+    Supplying both formNumber and elementKey preserves field-context parent filtering.
     """
     payload = {}
     if form_number:
@@ -932,7 +952,7 @@ def do_list_ref_layouts(cfg, token, form_number=None, element_key=None):
 
 
 def _find_element_type_by_key(metadata, key):
-    """返回使用精确 key 发布的任意元素类型。"""
+    """Return the type of any element published under an exact key."""
     target = str(key or "").strip()
     if not target:
         return None
@@ -1151,7 +1171,7 @@ def do_get_form_config(cfg, token, form_id):
     """
     return _api_call(cfg, token, "getFormConfig", {"formId": form_id}, method="GET")
 def do_can_add_toolbar_item(cfg, token, form_number, toolbar_key=None, control_type=None):
-    """工具栏项添加预校验。调用服务端 FilterColumnHandler.canAddToolbarItem。
+    """工具栏项添加预校验. 调用服务端 FilterColumnHandler.canAddToolbarItem.
 
     Returns:
         dict: { allowed: bool, reason?: str }
@@ -1163,17 +1183,17 @@ def do_can_add_toolbar_item(cfg, token, form_number, toolbar_key=None, control_t
 def do_add_filter_column(cfg, token, form_number, field_key, parent_scope,
                           control_type=None, name=None, column_key=None,
                           after_column=None):
-    """快捷在过滤视图添加字段（form + commonfiltercolumn/schemefiltercolumn + add）。
+    """快捷在过滤视图添加Field (form + commonfiltercolumn/schemefiltercolumn + add) .
 
     Returns:
         (form_id, [op])
     """
     if parent_scope not in FILTER_VIEW_PARENT_KEYS:
         raise ValueError(
-            f"parentScope 非法: '{parent_scope}'，必须为 "
+            f"parentScope Invalid: '{parent_scope}', must be "
             f"{sorted(FILTER_VIEW_PARENT_KEYS.keys())}"
         )
-    # 强制规范化：服务端真正识别无 ap 后缀版
+    # 强制规范化: 服务端真正识别无 ap 后缀版
     parent_scope = _normalize_filter_parent_scope(parent_scope)
     element_type = "schemefiltercolumn" if parent_scope == "schemefilterview" else "commonfiltercolumn"
 
@@ -1182,16 +1202,16 @@ def do_add_filter_column(cfg, token, form_number, field_key, parent_scope,
     print(f"[addFilterColumn] formNumber={form_number} → formId={form_id}, parentScope={parent_scope}",
           flush=True)
 
-    # 2. 查字段以回填 name / 推导 controlType
+    # 2. 查Field以回填 name / 推导 controlType
     field_meta = None
-    parent_meta = None   # 引用属性场景下所属的父字段元信息
-    sub_key = None       # 引用属性场景下的子 key
+    parent_meta = None   # 引用属性场景下所属的父Field元信息
+    sub_key = None       # Sub key in reference attribute scenario
     if field_key:
         elements_result = do_list_elements(cfg, token, form_number, category="field")
         if _is_api_success(elements_result):
             elements_data = elements_result.get("data") or []
             if "." in field_key:
-                # 引用属性场景（parent.sub）：定位父字段元信息
+                # 引用属性场景 (parent.sub) : 定位父Field元信息
                 parent_selector, sub_key = field_key.split(".", 1)
                 parent_meta, parent_key = _lookup_field_meta(
                     elements_data, parent_selector, "addFilterColumn"
@@ -1224,7 +1244,7 @@ def do_add_filter_column(cfg, token, form_number, field_key, parent_scope,
         default_name = field_key
         field_type = ""
 
-    # 3. 推导 controlType（显式传入优先）
+    # 3. 推导 controlType (显式传入优先)
     if not control_type:
         if parent_scope == "schemefilterview":
             control_type = _SCHEME_FILTER_TYPE_MAP.get(field_type, "SchemeFilterColumnAp")
@@ -1232,10 +1252,10 @@ def do_add_filter_column(cfg, token, form_number, field_key, parent_scope,
             control_type = "FilterColumnAp"
         else:
             control_type = _COMMON_FILTER_TYPE_MAP.get(field_type, "CommonFilterColumnAp")
-        print(f"[addFilterColumn] 字段 '{field_key}' 类型 '{field_type}' → controlType={control_type}",
+        print(f"[addFilterColumn] Field '{field_key}' type '{field_type}' → controlType={control_type}",
               flush=True)
 
-    # 4. 构造 op
+    # 4. Build op
     resolved_key = column_key or field_key
     resolved_name = name or default_name
     value = {
@@ -1271,7 +1291,7 @@ def _metadata_nodes(value, parent_key=""):
 
 
 def _runtime_entity_property_keys(entity_type_result):
-    """从 getEntityType 的完整实体图提取可查询运行时属性。"""
+    """Return queryable property keys from the full runtime entity graph."""
     if not _is_api_success(entity_type_result):
         return set()
     document = entity_type_result.get("data")
@@ -1301,11 +1321,12 @@ def _runtime_entity_property_keys(entity_type_result):
 
 
 def _composite_field_projections(metadata):
-    """把设计态组合控件编译为可查询的运行时属性。
+    """Compile authored composite controls to their runtime-query properties.
 
-    DateRangeField 在设计态是一个字段，运行时却持久化为两个 DateProp。列表元数据按
-    运行时实体求值，直接绑定设计态 key 会触发 FIELDNOTEXISTS000005。该映射属于
-    平台元模型知识，应固化在列表编译器中，而不是让模型现场猜测。
+    DateRangeField is one authored field but persists two DateProp values.  List
+    metadata is evaluated against the runtime entity, so binding the authored key
+    produces FIELDNOTEXISTS000005.  Keep the mapping here, beside list compilation,
+    instead of asking the model to rediscover platform storage semantics.
     """
     projections = {}
     for node, _ in _metadata_nodes(metadata):
@@ -1324,14 +1345,14 @@ def _composite_field_projections(metadata):
             else "header"
         )
         projections[logical_key] = [
-            {"key": start_key, "name": f"{name}.开始", "type": "DateField", "ownerScope": owner_scope},
-            {"key": end_key, "name": f"{name}.结束", "type": "DateField", "ownerScope": owner_scope},
+            {"key": start_key, "name": f"{name}.Start", "type": "DateField", "ownerScope": owner_scope},
+            {"key": end_key, "name": f"{name}.End", "type": "DateField", "ownerScope": owner_scope},
         ]
     return projections
 
 
 def _runtime_property_supports(field_key, runtime_keys):
-    """接受精确运行时属性以及引用字段子属性。"""
+    """Accept exact runtime properties and reference sub-properties."""
     key = str(field_key or "").strip()
     return key in runtime_keys or ("." in key and key.split(".", 1)[0] in runtime_keys)
 def _normalise_metadata_parent(value):
@@ -1365,6 +1386,74 @@ def _list_column_properties(column):
     return properties
 
 
+def _compile_list_column_properties(rows, column):
+    """Use the actual column declaration, preserving the field binding and identity."""
+    compiled, declarations, errors = {}, {}, []
+    aliases = {"wrap": "AutoTextWrap", "自动换行": "AutoTextWrap", "换行": "AutoTextWrap",
+               "align": "TextAlign", "文本对齐": "TextAlign", "对齐": "TextAlign",
+               "汇总": "Summary", "零值显示": "ZeroShow", "列宽": "Width"}
+    known = {"Summary", "ZeroShow", "AutoTextWrap", "TextAlign", "Width", "DisplayFormatString",
+             "ColumnOrderAndFilter", "Hyperlink", "Visible", "Mask", "ShowStyle"}
+    for requested in (_list_column_properties(column), column.get("properties") or {}):
+        for selector, value in requested.items():
+            original = selector
+            declaration, error = _resolve_property_declaration(rows, selector)
+            if error and str(selector).casefold() in aliases:
+                selector = aliases[str(selector).casefold()]
+                declaration, error = _resolve_property_declaration(rows, selector)
+            if error:
+                names = {str(row.get("propertyName") or ""): row for row in rows}
+                near = difflib.get_close_matches(str(selector).casefold(), [key.casefold() for key in names], n=3, cutoff=0.45)
+                error["data"] = {**error.get("data", {}), "requestedSelector": original,
+                    "suggestions": [{key: row.get(key) for key in ("propertyName", "displayName", "options")}
+                                    for name, row in names.items() if name.casefold() in near],
+                    "capabilityLimitConfirmed": selector in known}
+                errors.append(error)
+                continue
+            name = declaration["propertyName"]
+            if name == "TextAlign" and isinstance(value, str):
+                value = {"左": "left", "左对齐": "left", "右": "right", "右对齐": "right", "居中": "center"}.get(value, value)
+            if name in {"Key", "Id", "_Type_", "ListFieldId", "ParentId", "Index", "DataType", "SeqColumnType"}:
+                errors.append(_list_configuration_preflight_failure(
+                    "LIST_COLUMN_IDENTITY_PROPERTY_FORBIDDEN", "Use fieldKey/entity for binding; column identity is not a presentation property", propertyName=name))
+                continue
+            if isinstance(value, bool) and declaration.get("editorType") != "checkbox" and any(
+                    isinstance(option.get("id"), (int, float)) and not isinstance(option.get("id"), bool)
+                    for option in declaration.get("options") or []):
+                errors.append(_list_configuration_preflight_failure(
+                    "PROPERTY_VALUE_INVALID", "A boolean is not a numeric enum option", propertyName=name))
+                continue
+            if isinstance(value, (dict, list)) and declaration.get("editorType") not in {"dimension", "mcombo"}:
+                errors.append(_list_configuration_preflight_failure(
+                    "PROPERTY_REQUIRES_COMPLEX_SETTER", "Use the dedicated complex-property setter for structured values", propertyName=name))
+                continue
+            # The generic mcombo declaration omits list-only flags that are present
+            # in the persisted value (notably default/lookup). Reuse only observed IDs.
+            if name == "Visible" and declaration.get("editorType") == "mcombo":
+                options = declaration.get("options") or []
+                existing_ids = {str(option.get("id")) for option in options}
+                observed = str(declaration.get("currentValue") or "").split(",")
+                declaration = {**declaration, "options": [*options, *[
+                    {"id": flag.strip(), "name": flag.strip()} for flag in observed
+                    if flag.strip() and flag.strip() not in existing_ids]]}
+            values, schema, error = _compile_simple_property_map([declaration], {selector: value})
+            if error:
+                errors.extend((error.get("data") or {}).get("errors") or [error])
+                continue
+            if name in compiled and not _property_values_equal(compiled[name], values[name], schema[name]):
+                errors.append(_list_configuration_preflight_failure(
+                    "LIST_COLUMN_PROPERTY_CONFLICT", "Conflicting column options and properties", propertyName=name))
+                continue
+            compiled.update(values)
+            declarations.update(schema)
+    if errors:
+        return None, None, {"status": False,
+            "errorCode": errors[0]["errorCode"] if len(errors) == 1 else "PROPERTY_PREFLIGHT_FAILED",
+            "message": "Column property validation failed; all invalid selectors are listed",
+            "data": {"writeAttempted": False, "errors": errors}}
+    return compiled, declarations, None
+
+
 def _list_configuration_preflight_failure(code, message, **data):
     return {
         "status": False,
@@ -1414,7 +1503,10 @@ def do_configure_list(
     for index, column in enumerate(configuration.get("columns") or []):
         if (
             not isinstance(column, dict)
-            or set(column) - {"fieldKey", "entity", "order", "hyperlink", "displayName"}
+            or set(column) - {"fieldKey", "entity", "order", "hyperlink", "displayName", "properties"}
+            or "properties" in column and (not isinstance(column["properties"], dict) or not column["properties"])
+            or "hyperlink" in column and not isinstance(column["hyperlink"], bool)
+            or "order" in column and column["order"] not in {"ASC", "DESC", "NotOrder"}
             or not isinstance(column.get("fieldKey"), str)
             or not column["fieldKey"].strip()
             or "displayName" in column and (
@@ -1423,7 +1515,7 @@ def do_configure_list(
         ):
             return _list_configuration_preflight_failure(
                 "LIST_CONFIGURATION_INVALID",
-                f"columns[{index}] requires fieldKey and accepts only entity, order, hyperlink, and non-empty displayName",
+                f"columns[{index}] requires fieldKey and accepts entity, order, boolean hyperlink, non-empty displayName and a non-empty properties map",
             )
     columns = [
         dict(column) for column in configuration.get("columns") or []
@@ -1487,7 +1579,7 @@ def do_configure_list(
     ):
         return _list_configuration_preflight_failure(
             "LIST_CONFIGURATION_BASELINE_FAILED",
-            "写入列表前无法同时读取设计态和运行态元数据",
+            "could not read design and runtime metadata before list mutation",
             failedReads={
                 name: item
                 for name, item in (
@@ -1509,7 +1601,7 @@ def do_configure_list(
     if not runtime_keys:
         return _list_configuration_preflight_failure(
             "LIST_CONFIGURATION_RUNTIME_SCHEMA_INVALID",
-            "getEntityType 未返回可查询的运行时属性",
+            "getEntityType returned no queryable runtime properties",
             formNumber=form_number,
         )
     fields = {
@@ -1557,6 +1649,11 @@ def do_configure_list(
 
     def _resolve_field_selector(raw_selector, entity_selector=""):
         selector = str(raw_selector or "").strip()
+        # Preserve exact field captions first; otherwise honor an explicit header prefix.
+        if not entity_selector and selector.startswith("表头") and not any(
+                str(row.get("name") or "").strip() == selector for row in fields.values()):
+            selector = selector[2:].lstrip(" .:：")
+            entity_selector = "header"
         entity_keys = _entity_candidates(entity_selector) if entity_selector else None
         if entity_selector and not entity_keys:
             return None
@@ -1678,7 +1775,7 @@ def do_configure_list(
     if unresolved_selectors:
         return _list_configuration_preflight_failure(
             "LIST_CONFIGURATION_FIELD_AMBIGUOUS_OR_NOT_FOUND",
-            "列表字段名称未解析到唯一字段和实体",
+            "list field selectors did not resolve to one exact field and entity",
             unresolvedSelectors=sorted(set(unresolved_selectors)),
             candidates=[
                 {
@@ -1690,6 +1787,11 @@ def do_configure_list(
             ],
         )
 
+    resolved_keys = [column["fieldKey"] for column in normalized_columns]
+    if len(resolved_keys) != len(set(resolved_keys)):
+        return _list_configuration_preflight_failure(
+            "LIST_COLUMN_DUPLICATE", "Use one entry per field and combine its properties", fieldKeys=resolved_keys)
+
     composite_mappings = {}
     expanded_columns = []
     unsupported_composites = []
@@ -1743,7 +1845,7 @@ def do_configure_list(
     if unsupported_composites:
         return _list_configuration_preflight_failure(
             "LIST_CONFIGURATION_COMPOSITE_OPTION_UNSUPPORTED",
-            "组合字段不能直接指定统一列标题或作为快捷搜索、超链接、排序目标",
+            "composite fields cannot have one displayName or be quick-search, hyperlink, or sort targets",
             fields=sorted(set(unsupported_composites)),
         )
     configuration = {
@@ -1774,7 +1876,7 @@ def do_configure_list(
     if runtime_missing:
         return _list_configuration_preflight_failure(
             "LIST_CONFIGURATION_RUNTIME_FIELD_UNRESOLVED",
-            "列表字段在运行态实体中不存在",
+            "list fields are absent from the runtime entity schema",
             missingRuntimeFields=runtime_missing,
             compositeMappings=composite_mappings,
         )
@@ -1786,8 +1888,15 @@ def do_configure_list(
     }
     structural_ops = []
     property_targets = []
+    expected_columns = {}
+    column_errors = []
+    column_declarations = {}
+    property_schemas = {}
+    metadata_columns = {str(node.get("Key") or ""): node for node, _ in _metadata_nodes(metadata_document)
+                        if str(node.get("_Type_") or "").endswith("ListColumnAp")}
 
-    # 收敛旧版本直接绑定设计态组合字段 key 的无效列表配置。
+
+    # Repair legacy list bindings that used an authored composite key directly.
     for logical_key in composite_mappings:
         existing = by_field.get(logical_key)
         if existing is not None:
@@ -1816,6 +1925,30 @@ def do_configure_list(
         field_key = str(column.get("fieldKey") or "").strip()
         existing = by_field.get(field_key)
         requested_props = _list_column_properties(column)
+        if column.get("properties"):
+            schema_key = str((existing or {}).get("key") or "")
+            if not schema_key:
+                wanted_type = _LISTCOLUMN_TYPE_MAP.get(str(fields[field_key].get("type") or ""), "ListColumnAp")
+                schema_key = next((key for key, node in metadata_columns.items() if node.get("_Type_") == wanted_type), "")
+            if schema_key:
+                if schema_key not in property_schemas:
+                    property_schemas[schema_key] = do_get_property_schema(cfg, token, form_number, schema_key)
+                schema = property_schemas[schema_key]
+                if not _is_api_success(schema):
+                    return _list_configuration_preflight_failure("LIST_COLUMN_SCHEMA_FAILED", "Cannot read the column property contract", fieldKey=field_key, schema=schema)
+                requested_props, declarations, rejection = _compile_list_column_properties(schema.get("data") or [], column)
+                if rejection:
+                    column_errors.append(_list_configuration_preflight_failure("LIST_COLUMN_PROPERTY_INVALID", "Column properties failed preflight",
+                        fieldKey=field_key, columnKey=schema_key, propertyError=rejection,
+                        recovery={"command": "getPropertySchema", "arguments": ["--formNumber", form_number, "--elementKey", schema_key],
+                                  "scope": "this column only; do not query form structure or global help"},
+                        completion={"outcome": "failed_preflight", "requiresArtifactFinalization": False,
+                                    "nextAction": "respond_unmet_property" if any((item.get("data") or {}).get("capabilityLimitConfirmed")
+                                        for item in (rejection.get("data") or {}).get("errors", [])) else "repair_only_reported_input",
+                                    "message": "Zero writes. Do not render or reuse a card, launch source sync, or call output_check."}))
+                    continue
+                column_declarations[field_key] = declarations
+        expected_columns[field_key] = requested_props
         if existing is None:
             field_meta = fields[field_key]
             column_type = _LISTCOLUMN_TYPE_MAP.get(
@@ -1837,8 +1970,8 @@ def do_configure_list(
                 },
                 "value": value,
             })
-            if requested_props:
-                property_targets.append((f"listcol_{field_key}", requested_props, True))
+            if requested_props or column.get("properties"):
+                property_targets.append((f"listcol_{field_key}", requested_props, True, column))
         else:
             column_key = str(existing.get("key") or f"listcol_{field_key}").strip()
             if requested_props:
@@ -1848,13 +1981,20 @@ def do_configure_list(
                 current_data = (current.get("data") or {}) if _is_api_success(current) else {}
                 pending = {
                     name: value for name, value in requested_props.items()
-                    if current_data.get(
-                        name,
-                        current_data.get(name[:1].lower() + name[1:]),
-                    ) != value
+                    if not _property_values_equal(
+                        value, current_data.get(name, current_data.get(name[:1].lower() + name[1:])),
+                        column_declarations.get(field_key, {}).get(name))
                 }
                 if pending:
-                    property_targets.append((column_key, pending, False))
+                    property_targets.append((column_key, pending, False, column))
+
+    if column_errors:
+        details = [{**item["data"]} for item in column_errors]
+        result = column_errors[0]
+        result["data"]["columnErrors"] = details
+        if any((item.get("completion") or {}).get("nextAction") == "respond_unmet_property" for item in details):
+            result["data"]["completion"]["nextAction"] = "respond_unmet_property"
+        return result
 
     filter_specs = (
         [(key, "fastsearchgridview") for key in configuration.get("quickSearch") or []]
@@ -1907,10 +2047,32 @@ def do_configure_list(
                 "data": {"structuralResult": structural_result},
             }
 
+    created_columns = {}
+    if any(created and column.get("properties") for _key, _props, created, column in property_targets):
+        created_schema = do_get_form_schema(cfg, token, form_id)
+        if not _is_api_success(created_schema):
+            return {"status": False, "errorCode": "LIST_COLUMN_SCHEMA_FAILED", "message": "Cannot resolve created column identities",
+                    "data": {"writeAttempted": True, "structuralResult": structural_result}}
+        created_columns = {str(item.get("listFieldId") or ""): item for item in (created_schema.get("data") or {}).get("listColumns") or []}
     property_results = []
-    for element_key, properties, created in property_targets:
-        if created:
+    for element_key, properties, created, column in property_targets:
+        if created and not column.get("properties"):
             continue
+        if created:
+            element_key = str((created_columns.get(column["fieldKey"]) or {}).get("key") or "")
+            if not element_key:
+                return {"status": False, "errorCode": "LIST_COLUMN_IDENTITY_UNRESOLVED", "message": "Created column has no verified persisted key",
+                        "data": {"writeAttempted": True, "structuralResult": structural_result, "fieldKey": column["fieldKey"]}}
+            schema = do_get_property_schema(cfg, token, form_number, element_key)
+            if not _is_api_success(schema):
+                return {"status": False, "errorCode": "LIST_COLUMN_SCHEMA_FAILED", "message": "Column created but its property contract could not be read",
+                        "data": {"writeAttempted": True, "structuralResult": structural_result, "elementKey": element_key}}
+            properties, declarations, rejection = _compile_list_column_properties(schema.get("data") or [], column)
+            if rejection:
+                return {"status": False, "errorCode": "LIST_COLUMN_PROPERTY_INVALID", "message": "Column created; unsupported properties were not written",
+                        "data": {"writeAttempted": True, "structuralResult": structural_result, "elementKey": element_key, "propertyError": rejection}}
+            expected_columns[column["fieldKey"]] = properties
+            column_declarations[column["fieldKey"]] = declarations
         result = do_set_properties(cfg, token, form_number, element_key, properties)
         property_results.append({"elementKey": element_key, "result": result})
         if not _is_api_success(result):
@@ -1939,7 +2101,7 @@ def do_configure_list(
             errors.append(f"list column missing for field {field_key}")
             continue
         element_key = str(actual_column.get("key") or f"listcol_{field_key}").strip()
-        expected = _list_column_properties(column)
+        expected = expected_columns.get(field_key, _list_column_properties(column))
         evidence = {"fieldKey": field_key, "columnKey": element_key, "properties": {}}
         column_evidence.append(evidence)
         if not expected:
@@ -1955,9 +2117,9 @@ def do_configure_list(
             actual_value = actual.get(prop_name)
             if actual_value is None:
                 actual_value = actual.get(prop_name[:1].lower() + prop_name[1:])
-            evidence["properties"][prop_name] = {"requested": expected_value, "actual": actual_value,
-                                                  "matched": actual_value == expected_value}
-            if actual_value != expected_value:
+            matched = _property_values_equal(expected_value, actual_value, column_declarations.get(field_key, {}).get(prop_name))
+            evidence["properties"][prop_name] = {"requested": expected_value, "actual": actual_value, "matched": matched}
+            if not matched:
                 errors.append(
                     f"{element_key}.{prop_name}: expected {expected_value!r}, got {actual_value!r}"
                 )
@@ -1970,18 +2132,22 @@ def do_configure_list(
             errors.append(f"{parent_scope} missing field {field_key}")
     for logical_key in composite_mappings:
         if logical_key in after_by_field:
-            errors.append(f"仍存在组合字段的旧列表绑定: {logical_key}")
+            errors.append(f"legacy composite list binding still present for {logical_key}")
         if _filter_column_present(final_metadata, logical_key, "filtergridview"):
-            errors.append(f"仍存在组合字段的旧过滤绑定: {logical_key}")
+            errors.append(f"legacy composite filter binding still present for {logical_key}")
 
     configured_runtime_keys = set(after_by_field).intersection(requested_keys)
-    configured_runtime_keys.update(field_key for field_key, _ in filter_specs)
+    configured_runtime_keys.update(
+        field_key for field_key, _ in filter_specs
+    )
     invalid_runtime_bindings = sorted(
         key for key in configured_runtime_keys
         if not _runtime_property_supports(key, runtime_keys)
     )
     if invalid_runtime_bindings:
-        errors.append(f"运行态实体不包含列表字段 {invalid_runtime_bindings}")
+        errors.append(
+            f"runtime entity does not expose list fields {invalid_runtime_bindings}"
+        )
 
     verified = not errors and _is_api_success(schema_after) and _is_api_success(metadata_after)
     return {
@@ -2013,21 +2179,22 @@ def do_configure_list(
                 "scope": "requested_list_configuration",
                 "outcome": "verified" if structural_ops or property_results else "verified_noop",
                 "requiresArtifactFinalization": bool(structural_ops or property_results),
-                "message": "The requested list configuration is complete; the actual read-back is in verification. "
-                           "Do not rediscover or reverify these same concerns. Continue only other explicit user concerns; "
-                           "otherwise present the result using the returned appRoot and formNumber. A verified no-op does not require another card.",
+                "nextAction": "deliver_verified_change" if structural_ops or property_results else "respond_no_change",
+                "message": ("The changed configuration is independently verified. Complete its returned delivery once; do not rediscover or reverify."
+                            if structural_ops or property_results else
+                            "No change: all requested values are independently verified. Respond directly; do not render or reuse cards, launch source sync, or call output_check."),
             }} if verified else {}),
         },
     }
 def _filter_column_key_candidates(column_key):
-    """生成过滤列 columnKey 的候选集，覆盖两套命名规则：
+    """生成过滤列 columnKey 的候选集, 覆盖两套命名规则:
 
-    - addFilter 新建列：columnKey == fieldKey（无前缀，如 billno / kdtest_wens_recname）
-    - buildMeta 继承/模板列：columnKey == 'col' + 字段标识（如 colname / colnumber / colbillno）
+    - addFilter 新建列: columnKey == fieldKey (无前缀, 如 billno / kdtest_wens_recname)
+    - buildMeta 继承/模板列: columnKey == 'col' + 字段标识 (如 colname / colnumber / colbillno)
 
-    上层 Agent 删除继承字段时通常只知道字段标识（name/number/billno），传入裸 key，
-    与真实继承列 key（colXXX）不匹配，服务端幂等 no-op 造成假成功。这里一次性生成
-    候选集，由 remove 幂等无害特性覆盖两套规则。返回去重且保序的列表。
+    上层 Agent 删除继承字段时通常只知道字段标识 (name/number/billno), 传入裸 key,
+    与真实继承列 key (colXXX) 不匹配, 服务端幂等 no-op 造成假成功. 这里一次性生成
+    候选集, 由 remove 幂等无害特性覆盖两套规则. 返回去重且保序的列表.
     """
     key = str(column_key or "").strip()
     candidates = []
@@ -2041,29 +2208,29 @@ def _filter_column_key_candidates(column_key):
     if key:
         _add("col" + key)
         if key.startswith("col"):
-            # 上层可能已传入 col 前缀形式；兜底补裸 key
+            # 上层可能已传入 col 前缀形式; 兜底补裸 key
             _add(key[3:])
     return candidates
 def do_remove_filter_column(cfg, token, form_number, column_key, parent_scope="filtergridview"):
-    """删除过滤字段（快捷命令）。
+    """删除过滤Field (快捷命令) .
 
-    对 columnKey 生成多候选（原始 / col 前缀 / 去 col 前缀），一次 modifyMeta 提交多个
-    remove op，覆盖新建列（key=fieldKey）与继承列（key=col+fieldKey）两套命名规则；
-    remove 对不存在的 key 幂等无害，不匹配的候选为 no-op。
+    对 columnKey 生成多候选 (原始 / col 前缀 / 去 col 前缀), 一次 modifyMeta 提交多个
+    remove op, 覆盖新建列 (key=fieldKey) 与继承列 (key=col+fieldKey) 两套命名规则;
+    remove 对不存在的 key 幂等无害, 不匹配的候选为 no-op.
 
     Returns:
         (form_id, [op, ...])
     """
     if parent_scope not in FILTER_VIEW_PARENT_KEYS:
         raise ValueError(
-            f"parentScope 非法: '{parent_scope}'，必须为 {sorted(FILTER_VIEW_PARENT_KEYS.keys())}"
+            f"parentScope Invalid: '{parent_scope}', must be {sorted(FILTER_VIEW_PARENT_KEYS.keys())}"
         )
-    # 强制规范化：服务端识别无 ap 后缀版
+    # 强制规范化: 服务端识别无 ap 后缀版
     parent_scope = _normalize_filter_parent_scope(parent_scope)
     if parent_scope == "schemefilterview":
         print(
-            "[removeFilterColumn][WARN] 正在删除方案过滤视图（schemefilterview）下的过滤字段，"
-            "这可能破坏已保存方案的过滤条件，请确认已与使用方沟通。",
+            "[removeFilterColumn][WARN] 正在删除Scheme filter视图 (schemefilterview) 下的过滤Field, "
+            "这可能破坏已保存方案的过滤条件, 请确认已与使用方沟通. ",
             flush=True,
         )
     element_type = "schemefiltercolumn" if parent_scope == "schemefilterview" else "commonfiltercolumn"
@@ -2071,7 +2238,7 @@ def do_remove_filter_column(cfg, token, form_number, column_key, parent_scope="f
     candidates = _filter_column_key_candidates(column_key)
     print(
         f"[removeFilterColumn] columnKey='{column_key}' → 候选key={candidates} "
-        f"（覆盖新建列key=fieldKey与继承列key=col+fieldKey两套规则）",
+        f"(覆盖新建列key=fieldKey与继承列key=col+fieldKey两套规则)",
         flush=True,
     )
     ops = [