@josephyan/qingflow-cli 0.2.0-beta.985 → 0.2.0-beta.987

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-cli@0.2.0-beta.985
+npm install @josephyan/qingflow-cli@0.2.0-beta.987
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-cli@0.2.0-beta.985 qingflow
+npx -y -p @josephyan/qingflow-cli@0.2.0-beta.987 qingflow
 ```
 
 Environment:

package/docs/local-agent-install.md

@@ -6,6 +6,20 @@
 2. 记录/待办优先的 `qingflow-app-user-mcp`
 3. 精简 builder 的 `qingflow-app-builder-mcp`
 
+## 本地鉴权推荐方案
+
+本地模式现在推荐优先使用 `credential` 建立会话，而不是直接注入 `token`。
+
+推荐链路：
+
+1. createClaw 或其它本地宿主为当前实例保存 `credential`
+2. 本地 MCP 调用 `auth_use_credential`
+3. MCP 用该 `credential` 请求 apaas `/mcp/auth/context`
+4. 解析并保存 `token / wsId / qfVersion / uid`
+5. 业务工具直接使用这份上下文
+
+`auth_use_credential` 是本地唯一鉴权主路径。
+
 ## npm 安装器适用场景
 
 适合这类本地 agent / gateway：
@@ -63,17 +77,17 @@ npm run pack:npm
 会生成：
 
 ```bash
-dist/npm/josephyan-qingflow-cli-<version>.tgz
-dist/npm/josephyan-qingflow-app-user-mcp-<version>.tgz
-dist/npm/josephyan-qingflow-app-builder-mcp-<version>.tgz
+dist/npm/qingflow-tech-qingflow-cli-<version>.tgz
+dist/npm/qingflow-tech-qingflow-app-user-mcp-<version>.tgz
+dist/npm/qingflow-tech-qingflow-app-builder-mcp-<version>.tgz
 ```
 
 然后在目标机器安装：
 
 ```bash
-npm install /absolute/path/to/dist/npm/josephyan-qingflow-cli-<version>.tgz
-npm install /absolute/path/to/dist/npm/josephyan-qingflow-app-user-mcp-<version>.tgz
-npm install /absolute/path/to/dist/npm/josephyan-qingflow-app-builder-mcp-<version>.tgz
+npm install /absolute/path/to/dist/npm/qingflow-tech-qingflow-cli-<version>.tgz
+npm install /absolute/path/to/dist/npm/qingflow-tech-qingflow-app-user-mcp-<version>.tgz
+npm install /absolute/path/to/dist/npm/qingflow-tech-qingflow-app-builder-mcp-<version>.tgz
 ```
 
 安装时会自动：
@@ -136,7 +150,10 @@ qingflow-app-builder-mcp
       ],
       "env": {
         "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
-        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp"
+        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp",
+        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
+        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
+        "QINGFLOW_MCP_CREDIT_APAAS_PATH": "/user/credit/usage"
       }
     }
   }
@@ -153,7 +170,10 @@ qingflow-app-builder-mcp
       "args": [],
       "env": {
         "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
-        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp"
+        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp",
+        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
+        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
+        "QINGFLOW_MCP_CREDIT_APAAS_PATH": "/user/credit/usage"
       }
     }
   }
@@ -170,7 +190,10 @@ qingflow-app-builder-mcp
       "args": [],
       "env": {
         "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
-        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp"
+        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp",
+        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
+        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
+        "QINGFLOW_MCP_CREDIT_APAAS_PATH": "/user/credit/usage"
       }
     }
   }
@@ -191,7 +214,10 @@ qingflow-app-builder-mcp
         "@josephyan/qingflow-app-user-mcp"
       ],
       "env": {
-        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api"
+        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
+        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
+        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
+        "QINGFLOW_MCP_CREDIT_APAAS_PATH": "/user/credit/usage"
       }
     },
     "qingflow-builder": {
@@ -201,7 +227,10 @@ qingflow-app-builder-mcp
         "@josephyan/qingflow-app-builder-mcp"
       ],
       "env": {
-        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api"
+        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
+        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
+        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
+        "QINGFLOW_MCP_CREDIT_APAAS_PATH": "/user/credit/usage"
       }
     }
   }
@@ -212,6 +241,7 @@ qingflow-app-builder-mcp
 - 源码目录 `npm install` 不会把命令加到全局 PATH；这种模式请用 `node ./npm/bin/qingflow.mjs`、`node ./npm/bin/qingflow-app-user-mcp.mjs` 或 `node ./npm/bin/qingflow-app-builder-mcp.mjs`
 - `npx` 方式适合临时安装或容器化本地 agent
 - 全局安装方式更适合长期固定使用的本机开发环境
+- 计费接口使用当前登录会话的 `token` 与 `wsId` 请求头，可通过 `QINGFLOW_MCP_CREDIT_APAAS_BASE_URL/PATH` 覆盖调用记录接口地址
 
 ## 排障
 
@@ -242,3 +272,32 @@ npm install
 4. 再启动 MCP 客户端
 
 现在 stdio MCP 入口会拒绝在启动瞬间“边启动边重建 Python 运行时”，因为安装日志一旦写进 stdout，就会破坏 MCP 握手并表现成 `Transport closed`。如果运行时缺失或版本不一致，入口会直接报错并提示重装，而不是静默自修复。
+
+## createClaw 本地接入示例
+
+如果 createClaw 已经为当前本地实例保存了 `credential`，推荐在首次建链时调用：
+
+```bash
+qingflow auth use-credential \
+  --base-url https://qingflow.com/api \
+  --credential-stdin
+```
+
+然后把 `credential` 写到 stdin。
+
+等价 MCP 工具调用参数：
+
+```json
+{
+  "profile": "default",
+  "base_url": "https://qingflow.com/api",
+  "credential": "1602853_277941",
+  "persist": false
+}
+```
+
+说明：
+
+- 本地会把解析后的 `token` 和原始 `credential` 写入 profile 文件，用于后续 CLI 命令恢复会话
+- `persist=true` 时，本地还会优先把解析后的 `token` 和原始 `credential` 同步写入系统 keychain
+- 当前工作区以 `/mcp/auth/context` 返回的 `wsId` 为准，不再通过本地 MCP 显式切换

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-cli",
-  "version": "0.2.0-beta.985",
+  "version": "0.2.0-beta.987",
   "description": "Human-friendly Qingflow command line interface for auth, record operations, import, tasks, and stable builder flows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "0.2.0b985"
+version = "0.2.0b987"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/src/qingflow_mcp/__init__.py

@@ -5,7 +5,7 @@ from pathlib import Path
 
 __all__ = ["__version__"]
 
-_FALLBACK_VERSION = "0.2.0b985"
+_FALLBACK_VERSION = "0.2.0b987"
 
 
 def _resolve_local_pyproject_version() -> str | None:

package/src/qingflow_mcp/builder_facade/service.py

@@ -7708,7 +7708,7 @@ class AiBuilderFacade:
                     "request_route": request_route,
                 },
                 suggested_next_call=(
-                    {"tool_name": "workspace_select", "arguments": {"profile": profile, "ws_id": request_route.get("ws_id")}}
+                    {"tool_name": "auth_use_credential", "arguments": {"profile": profile}}
                     if request_route.get("ws_id")
                     else None
                 ),
@@ -9811,6 +9811,15 @@ def _apply_relation_target_selection(
     config["refer_field_types"] = [item.get("type") for item in normalized_visible]
     config["auth_field_ids"] = [item.get("field_id") or item.get("name") for item in normalized_visible]
     config["auth_field_que_ids"] = [_coerce_positive_int(item.get("que_id")) or 0 for item in normalized_visible]
+    config["refer_auth_ques"] = [
+        {
+            "queId": _coerce_positive_int(item.get("que_id")) or 0,
+            "queAuth": _REFERENCE_FIELD_VISIBLE_AUTH,
+            "_field_id": item.get("field_id") or item.get("name"),
+        }
+        for item in normalized_visible
+        if (_coerce_positive_int(item.get("que_id")) or 0) > 0
+    ]
     config["field_name_show"] = bool(field.get("field_name_show", True))
     field["target_field_id"] = display_field.get("field_id") or display_field.get("name")
     field["target_field_que_id"] = _coerce_positive_int(display_field.get("que_id")) or 0
@@ -10071,17 +10080,32 @@ def _parse_field(question: dict[str, Any], *, field_id_hint: str | None = None)
         field["target_app_key"] = reference.get("referAppKey")
         field["relation_mode"] = _relation_mode_from_optional_data_num(reference.get("optionalDataNum"))
         refer_questions = reference.get("referQuestions") if isinstance(reference.get("referQuestions"), list) else []
+        refer_auth_questions = reference.get("referAuthQues") if isinstance(reference.get("referAuthQues"), list) else []
+        refer_auth_by_que_id: dict[int, int] = {}
+        for raw_item in refer_auth_questions:
+            if not isinstance(raw_item, dict):
+                continue
+            que_id = _coerce_nonnegative_int(raw_item.get("queId"))
+            que_auth = _coerce_nonnegative_int(raw_item.get("queAuth"))
+            if que_id is None or que_auth is None or que_id in refer_auth_by_que_id:
+                continue
+            refer_auth_by_que_id[que_id] = que_auth
         visible_fields: list[dict[str, Any]] = []
         display_field_que_id = _coerce_nonnegative_int(reference.get("referQueId"))
         display_field_name: str | None = None
         for item in refer_questions:
             if not isinstance(item, dict):
                 continue
+            que_id = _coerce_nonnegative_int(item.get("queId"))
+            que_auth = _coerce_nonnegative_int(item.get("queAuth"))
+            if que_auth is None and que_id is not None:
+                que_auth = refer_auth_by_que_id.get(que_id)
             selector = {
-                "que_id": _coerce_nonnegative_int(item.get("queId")),
+                "que_id": que_id,
                 "name": str(item.get("queTitle") or "").strip() or None,
             }
-            visible_fields.append(selector)
+            if que_auth != _REFERENCE_FIELD_HIDDEN_AUTH:
+                visible_fields.append(selector)
             if display_field_que_id is not None and selector["que_id"] == display_field_que_id:
                 display_field_name = selector["name"]
         if display_field_name is None and visible_fields:
@@ -13275,6 +13299,333 @@ def _normalize_reference_auth_question_for_save(value: Any) -> dict[str, Any] |
     return payload
 
 
+def _dedupe_reference_auth_questions(auth_questions: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    deduped: list[dict[str, Any]] = []
+    seen_que_ids: set[int] = set()
+    for item in auth_questions:
+        normalized_item = _normalize_reference_auth_question_for_save(item)
+        if normalized_item is None:
+            continue
+        que_id = _coerce_any_int(normalized_item.get("queId"))
+        if que_id is None or que_id in seen_que_ids:
+            continue
+        seen_que_ids.add(que_id)
+        deduped.append(normalized_item)
+    return deduped
+
+
+_REFERENCE_FIELD_HIDDEN_AUTH = 2
+_REFERENCE_FIELD_VISIBLE_AUTH = 3
+
+
+def _synthesize_reference_auth_questions_for_save(
+    *,
+    source: dict[str, Any],
+    field: dict[str, Any],
+) -> list[dict[str, Any]]:
+    config = field.get("config") if isinstance(field.get("config"), dict) else {}
+    synthesized: list[dict[str, Any]] = []
+
+    if isinstance(config.get("refer_auth_ques"), list):
+        synthesized.extend(cast(list[dict[str, Any]], config.get("refer_auth_ques") or []))
+    if synthesized:
+        return _dedupe_reference_auth_questions(synthesized)
+
+    refer_question_ids_by_name: dict[str, int] = {}
+    for raw_item in cast(list[Any], source.get("referQuestions") or []):
+        if not isinstance(raw_item, dict):
+            continue
+        que_id = _coerce_any_int(raw_item.get("queId"))
+        name = str(raw_item.get("queTitle") or "").strip()
+        if que_id is None or not name or name in refer_question_ids_by_name:
+            continue
+        refer_question_ids_by_name[name] = que_id
+
+    visible_fields = cast(list[dict[str, Any]], field.get("visible_fields") or [])
+    for item in visible_fields:
+        if not isinstance(item, dict):
+            continue
+        que_id = _coerce_any_int(item.get("que_id"))
+        if que_id is None:
+            name = str(item.get("name") or "").strip()
+            que_id = refer_question_ids_by_name.get(name)
+        if que_id is None:
+            continue
+        synthesized.append({"queId": que_id, "queAuth": _REFERENCE_FIELD_VISIBLE_AUTH})
+    if synthesized:
+        return _dedupe_reference_auth_questions(synthesized)
+
+    auth_field_que_ids = cast(list[Any], config.get("auth_field_que_ids") or [])
+    for raw_que_id in auth_field_que_ids:
+        que_id = _coerce_any_int(raw_que_id)
+        if que_id is None:
+            continue
+        synthesized.append({"queId": que_id, "queAuth": _REFERENCE_FIELD_VISIBLE_AUTH})
+    if synthesized:
+        return _dedupe_reference_auth_questions(synthesized)
+
+    for raw_item in cast(list[Any], source.get("referQuestions") or []):
+        if not isinstance(raw_item, dict):
+            continue
+        que_id = _coerce_any_int(raw_item.get("queId"))
+        if que_id is None:
+            continue
+        synthesized.append(
+            {
+                "queId": que_id,
+                "queAuth": _REFERENCE_FIELD_VISIBLE_AUTH,
+            }
+        )
+    if synthesized:
+        return _dedupe_reference_auth_questions(synthesized)
+
+    fallback_que_id = _coerce_any_int(field.get("target_field_que_id"))
+    if fallback_que_id is not None:
+        synthesized.append({"queId": fallback_que_id, "queAuth": _REFERENCE_FIELD_VISIBLE_AUTH})
+    return _dedupe_reference_auth_questions(synthesized)
+
+
+def _reference_question_auth_overrides_for_save(
+    *,
+    source: dict[str, Any],
+    field: dict[str, Any],
+) -> dict[int, int]:
+    overrides: dict[int, int] = {}
+    visible_que_ids: set[int] = set()
+
+    for item in cast(list[Any], field.get("visible_fields") or []):
+        if not isinstance(item, dict):
+            continue
+        que_id = _coerce_any_int(item.get("que_id"))
+        if que_id is not None:
+            visible_que_ids.add(que_id)
+
+    if not visible_que_ids:
+        refer_auth_ques = _synthesize_reference_auth_questions_for_save(source=source, field=field)
+        for item in refer_auth_ques:
+            que_id = _coerce_any_int(item.get("queId"))
+            que_auth = _coerce_nonnegative_int(item.get("queAuth"))
+            if que_id is None or que_auth is None:
+                continue
+            overrides[que_id] = que_auth
+        if overrides:
+            return overrides
+
+    for raw_item in cast(list[Any], source.get("referQuestions") or []):
+        if not isinstance(raw_item, dict):
+            continue
+        que_id = _coerce_any_int(raw_item.get("queId"))
+        if que_id is None:
+            continue
+        overrides[que_id] = (
+            _REFERENCE_FIELD_VISIBLE_AUTH if que_id in visible_que_ids else _REFERENCE_FIELD_HIDDEN_AUTH
+        )
+    return overrides
+
+
+def _reference_question_matches_visible_selector(question: dict[str, Any], selector: dict[str, Any]) -> bool:
+    question_que_id = _coerce_any_int(question.get("queId"))
+    selector_que_id = _coerce_any_int(selector.get("que_id"))
+    if question_que_id is not None and selector_que_id is not None and question_que_id == selector_que_id:
+        return True
+    question_name = str(question.get("queTitle") or "").strip()
+    selector_name = str(selector.get("name") or "").strip()
+    return bool(question_name and selector_name and question_name == selector_name)
+
+
+def _build_reference_question_from_visible_selector(
+    selector: dict[str, Any],
+    *,
+    ordinal: int,
+) -> dict[str, Any] | None:
+    return _normalize_reference_question_for_save(
+        {
+            "queId": _coerce_any_int(selector.get("que_id")),
+            "queTitle": str(selector.get("name") or "").strip() or None,
+            "queType": str(selector.get("type") or "2"),
+            "ordinal": ordinal,
+        },
+        ordinal=ordinal,
+    )
+
+
+def _canonicalize_reference_questions_for_save(
+    *,
+    source: dict[str, Any],
+    field: dict[str, Any],
+) -> list[dict[str, Any]]:
+    normalized_source_questions = [
+        item
+        for item in (
+            _normalize_reference_question_for_save(raw_item, ordinal=index)
+            for index, raw_item in enumerate(cast(list[Any], source.get("referQuestions") or []), start=1)
+        )
+        if item is not None
+    ]
+
+    display_field = field.get("display_field") if isinstance(field.get("display_field"), dict) else None
+    visible_fields = [item for item in cast(list[Any], field.get("visible_fields") or []) if isinstance(item, dict)]
+    ordered_visible_selectors: list[dict[str, Any]] = []
+    if display_field is not None:
+        ordered_visible_selectors.append(display_field)
+    for item in visible_fields:
+        if any(_relation_target_field_matches(existing, item) for existing in ordered_visible_selectors):
+            continue
+        ordered_visible_selectors.append(item)
+
+    if not ordered_visible_selectors:
+        return normalized_source_questions
+
+    canonical_questions: list[dict[str, Any]] = []
+    used_source_indexes: set[int] = set()
+
+    for ordinal, selector in enumerate(ordered_visible_selectors, start=1):
+        matched_index: int | None = None
+        matched_item: dict[str, Any] | None = None
+        for index, item in enumerate(normalized_source_questions):
+            if index in used_source_indexes:
+                continue
+            if _reference_question_matches_visible_selector(item, selector):
+                matched_index = index
+                matched_item = deepcopy(item)
+                break
+        if matched_item is None:
+            matched_item = _build_reference_question_from_visible_selector(selector, ordinal=ordinal)
+        if matched_item is None:
+            continue
+        matched_item["ordinal"] = ordinal
+        canonical_questions.append(matched_item)
+        if matched_index is not None:
+            used_source_indexes.add(matched_index)
+
+    next_ordinal = len(canonical_questions) + 1
+    for index, item in enumerate(normalized_source_questions):
+        if index in used_source_indexes:
+            continue
+        remaining_item = deepcopy(item)
+        remaining_item["ordinal"] = next_ordinal
+        next_ordinal += 1
+        canonical_questions.append(remaining_item)
+
+    return canonical_questions
+
+
+def _canonicalize_reference_auth_questions_for_save(
+    *,
+    source: dict[str, Any],
+    refer_questions: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    source_auth_questions = [
+        item
+        for item in (
+            _normalize_reference_auth_question_for_save(raw_item)
+            for raw_item in cast(list[Any], source.get("referAuthQues") or [])
+        )
+        if item is not None
+    ]
+    source_auth_by_que_id: dict[int, dict[str, Any]] = {}
+    for item in source_auth_questions:
+        que_id = _coerce_any_int(item.get("queId"))
+        if que_id is None or que_id in source_auth_by_que_id:
+            continue
+        source_auth_by_que_id[que_id] = item
+
+    auth_questions: list[dict[str, Any]] = []
+    for item in refer_questions:
+        que_id = _coerce_any_int(item.get("queId"))
+        que_auth = _coerce_nonnegative_int(item.get("queAuth"))
+        if que_id is None or que_auth is None:
+            continue
+        payload = deepcopy(source_auth_by_que_id.get(que_id) or {"queId": que_id})
+        payload["queId"] = que_id
+        payload["queAuth"] = que_auth
+        auth_questions.append(payload)
+    return _dedupe_reference_auth_questions(auth_questions)
+
+
+def _enforce_reference_config_consistency_for_save(
+    payload: dict[str, Any],
+    *,
+    field: dict[str, Any],
+) -> dict[str, Any]:
+    refer_questions = [
+        item
+        for item in (
+            _normalize_reference_question_for_save(raw_item, ordinal=index)
+            for index, raw_item in enumerate(cast(list[Any], payload.get("referQuestions") or []), start=1)
+        )
+        if item is not None
+    ]
+    if not refer_questions:
+        return payload
+
+    refer_auth_ques = _dedupe_reference_auth_questions(
+        [
+            item
+            for item in (
+                _normalize_reference_auth_question_for_save(raw_item)
+                for raw_item in cast(list[Any], payload.get("referAuthQues") or [])
+            )
+            if item is not None
+        ]
+    )
+    refer_auth_by_que_id: dict[int, int] = {}
+    for item in refer_auth_ques:
+        que_id = _coerce_any_int(item.get("queId"))
+        que_auth = _coerce_nonnegative_int(item.get("queAuth"))
+        if que_id is None or que_auth is None or que_id in refer_auth_by_que_id:
+            continue
+        refer_auth_by_que_id[que_id] = que_auth
+
+    display_field_que_id = _coerce_any_int(payload.get("referQueId"))
+    if display_field_que_id is None:
+        display_field_que_id = _coerce_any_int(field.get("target_field_que_id"))
+        if display_field_que_id is not None:
+            payload["referQueId"] = display_field_que_id
+
+    if display_field_que_id is not None and not any(
+        _coerce_any_int(item.get("queId")) == display_field_que_id for item in refer_questions
+    ):
+        display_selector = field.get("display_field") if isinstance(field.get("display_field"), dict) else None
+        display_question = (
+            _build_reference_question_from_visible_selector(display_selector, ordinal=1)
+            if display_selector is not None
+            else None
+        )
+        if display_question is not None:
+            display_question["queId"] = display_field_que_id
+            display_question["queAuth"] = _REFERENCE_FIELD_VISIBLE_AUTH
+            refer_questions = [display_question, *refer_questions]
+
+    if display_field_que_id is not None:
+        display_questions = [
+            item for item in refer_questions if _coerce_any_int(item.get("queId")) == display_field_que_id
+        ]
+        trailing_questions = [
+            item for item in refer_questions if _coerce_any_int(item.get("queId")) != display_field_que_id
+        ]
+        refer_questions = [*display_questions, *trailing_questions]
+
+    for ordinal, item in enumerate(refer_questions, start=1):
+        que_id = _coerce_any_int(item.get("queId"))
+        if que_id is None:
+            continue
+        item["ordinal"] = ordinal
+        item["queAuth"] = refer_auth_by_que_id.get(
+            que_id,
+            _coerce_nonnegative_int(item.get("queAuth")) or _REFERENCE_FIELD_VISIBLE_AUTH,
+        )
+        if display_field_que_id is not None and que_id == display_field_que_id:
+            item["queAuth"] = _REFERENCE_FIELD_VISIBLE_AUTH
+
+    payload["referQuestions"] = refer_questions
+    payload["referAuthQues"] = _canonicalize_reference_auth_questions_for_save(
+        source={"referAuthQues": refer_auth_ques},
+        refer_questions=refer_questions,
+    )
+    return payload
+
+
 def _normalize_reference_config_for_save(
     reference: Any,
     *,
@@ -13289,11 +13640,13 @@ def _normalize_reference_config_for_save(
     if field.get("field_name_show") is not None:
         payload["fieldNameShow"] = bool(field.get("field_name_show"))
 
-    refer_questions: list[dict[str, Any]] = []
-    for index, raw_item in enumerate(cast(list[Any], source.get("referQuestions") or []), start=1):
-        normalized_item = _normalize_reference_question_for_save(raw_item, ordinal=index)
-        if normalized_item is not None:
-            refer_questions.append(normalized_item)
+    refer_question_auth_overrides = _reference_question_auth_overrides_for_save(source=source, field=field)
+    refer_questions = _canonicalize_reference_questions_for_save(source=source, field=field)
+    for index, normalized_item in enumerate(refer_questions, start=1):
+        que_id = _coerce_any_int(normalized_item.get("queId"))
+        if que_id is not None and que_id in refer_question_auth_overrides:
+            normalized_item["queAuth"] = refer_question_auth_overrides[que_id]
+        normalized_item["ordinal"] = index
     if refer_questions or "referQuestions" in source:
         payload["referQuestions"] = refer_questions
 
@@ -13308,18 +13661,13 @@ def _normalize_reference_config_for_save(
     if refer_fill_rules or "referFillRules" in source:
         payload["referFillRules"] = refer_fill_rules
 
-    refer_auth_ques = [
-        item
-        for item in (
-            _normalize_reference_auth_question_for_save(raw_item)
-            for raw_item in cast(list[Any], source.get("referAuthQues") or [])
-        )
-        if item is not None
-    ]
+    refer_auth_ques = _canonicalize_reference_auth_questions_for_save(source=source, refer_questions=refer_questions)
+    if not refer_auth_ques:
+        refer_auth_ques = _synthesize_reference_auth_questions_for_save(source=source, field=field)
     if refer_auth_ques or "referAuthQues" in source:
         payload["referAuthQues"] = refer_auth_ques
 
-    return payload
+    return _enforce_reference_config_consistency_for_save(payload, field=field)
 
 
 def _normalize_relation_question_for_save(question: dict[str, Any], *, field: dict[str, Any]) -> dict[str, Any]:
@@ -13550,9 +13898,16 @@ def _field_to_question(field: dict[str, Any], *, temp_id: int) -> dict[str, Any]
             preserved_reference["referAppKey"] = field.get("target_app_key")
             question["referenceConfig"] = preserved_reference
         else:
+            existing_reference = (
+                deepcopy(relation_question_template.get("referenceConfig"))
+                if relation_question_template is not None and isinstance(relation_question_template.get("referenceConfig"), dict)
+                else deepcopy(question.get("referenceConfig"))
+                if isinstance(question.get("referenceConfig"), dict)
+                else {}
+            )
             reference = (
-                deepcopy(built_question.get("referenceConfig"))
-                if relation_config_explicit and isinstance(built_question.get("referenceConfig"), dict)
+                existing_reference
+                if relation_config_explicit
                 else deepcopy(question.get("referenceConfig"))
                 if isinstance(question.get("referenceConfig"), dict)
                 else {}
@@ -13573,6 +13928,8 @@ def _field_to_question(field: dict[str, Any], *, temp_id: int) -> dict[str, Any]
                 "fieldNameShow",
                 "_targetFieldId",
             ):
+                if relation_config_explicit and key in {"referQuestions", "referAuthQues"}:
+                    continue
                 if key in built_reference:
                     reference[key] = deepcopy(built_reference[key])
             reference["referAppKey"] = field.get("target_app_key")