@qingflow-tech/qingflow-cli 1.1.50-beta.4 → 1.1.50-beta.5

package/README.md

@@ -7,7 +7,7 @@ Qingflow CLI 是轻流面向开发者和 AI Agent 的命令行工具。它把轻
 ## 安装
 
 ```bash
-npm install @qingflow-tech/qingflow-cli@1.1.50-beta.4
+npm install @qingflow-tech/qingflow-cli@1.1.50-beta.5
 ```
 
 推荐从官网复制这一条一键安装 Qingflow CLI：
@@ -21,7 +21,7 @@ npx qingflow-cli@latest install
 ## 运行
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-cli@1.1.50-beta.4 qingflow
+npx -y -p @qingflow-tech/qingflow-cli@1.1.50-beta.5 qingflow
 ```
 
 全局安装后可以直接运行：
@@ -62,7 +62,7 @@ qingflow-skills install --agent codex --scope user
 如果你通过一次性 `npx -p` 执行 skills 安装，建议加 `--copy`，避免 symlink 指向 npm 临时执行缓存：
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-cli@1.1.50-beta.4 qingflow-skills install --agent codex --scope user --copy
+npx -y -p @qingflow-tech/qingflow-cli@1.1.50-beta.5 qingflow-skills install --agent codex --scope user --copy
 ```
 
 `qingflow-skills install` 默认使用 symlink，且遇到同名 skill 不会覆盖；只有显式传入 `--force` 才会替换。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-cli",
-  "version": "1.1.50-beta.4",
+  "version": "1.1.50-beta.5",
   "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 = "1.1.50b4"
+version = "1.1.50b5"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/skills/qingflow-cli/SKILL.md

@@ -14,6 +14,43 @@ description: |
 
 本 Skill 负责 CLI 入口、文件约定和业务分流。已知 `app_key` 时直接执行 `data query/get`。只有应用名称时，先用 `qingflow --json app list --query "应用名称"` 查找当前工作区的可见应用，并核对返回项的 `app_name/title`；目标明确且唯一时取其 `app_key` 再查询，否则请用户确认。不要把应用名称直接传给 `--app-key`，也不要为定位名称转向 builder 或切换工作区。字段能力、权限范围与下一步动作以当前工具 schema、data 响应和 `hints` 为准。
 
+## 关联文件
+
+
+| 文件                                                                                               | 说明                                                                                                                                                                                                                                                                                    |
+| ------------------------------------------------------------------------------------------------ |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `manifest.yaml`                                                                                  | 技能清单                                                                                                                                                                                                                                                                                  |
+| [reference/00-INDEX.md](./reference/00-INDEX.md) | **总导航**：按用户目标选择 record / task / builder 文档；复杂任务先读 |
+| [reference/QINGFLOW_CLI_MEMBER_CHEATSHEET.md](./reference/core/QINGFLOW_CLI_MEMBER_CHEATSHEET.md)     | **普通成员**主线：最短路径、`view_id`、与管理命令的差异预期                                                                                                                                                                                                                                                  |
+| [reference/QINGFLOW_CLI_FIELD_DATA_TYPES.md](./reference/core/QINGFLOW_CLI_FIELD_DATA_TYPES.md)       | **字段数据类型**：`record schema …` 的 `fields[]`（`field_id`、`title`、`kind`、`options`…）；`record list/get/access` 与写入 payload 的形态对照                                                                                                                                                                    |
+| [reference/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./reference/core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md) | **应用记录获取数据**：`app get`（`accessible_views`）→ `record schema browse` → `record list(query)` 模糊定位 / `record get` 详情页首屏上下文 / `record logs` 全量日志；分析取数转 `record_access`                                                                                                                                                                        |
+| [reference/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md](./reference/task/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md) | **任务(待办已办)上下文 SOP**：`task list` → `task get` → `task log` → `task report` → `task action`；只把 `task_id` 作为主定位参数                                                                                               |
+| [reference/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md) | **批量导入 SOP**：`app_get`（**`import_capability`**）→ `record_import_template_get` → `record_import_verify` →（可选）`record_import_repair_local` → `record_import_start` → `record_import_status_get`；CLI `import` / `record schema import`                                                   |
+| [reference/builder/README.md](./reference/builder/README.md) | **Builder 总导航**：完整系统、单应用、字段、布局、视图、报表、门户、按钮/关联资源、流程、发布校验 |
+| [reference/builder/10-build-single-app.md](./reference/builder/10-build-single-app.md) | **单应用搭建主入口**：一个应用端到端交付顺序 |
+| [reference/builder/20-build-complete-system.md](./reference/builder/20-build-complete-system.md) | **完整系统/应用包主入口**：多应用、跨应用 relation、门户闭环 |
+| [reference/builder/30-schema-fields.md](./reference/builder/30-schema-fields.md) | **字段 / schema**：字段类型、直觉别名、数据标题/封面、schema 创建与更新 |
+| [reference/builder/40-layout.md](./reference/builder/40-layout.md) | **布局维护**：仅用于已有应用的分组、`rows` 矩阵、布局修复；新建应用布局写在 `form` 内 |
+| [reference/builder/50-views.md](./reference/builder/50-views.md) | **视图**：表格/卡片/看板/甘特、固定筛选、查询面板、视图 patch |
+| [reference/builder/60-charts.md](./reference/builder/60-charts.md) | **报表 / QingBI**：指标卡、图表、语义聚合、筛选、排序、更新 |
+| [reference/builder/70-portal.md](./reference/builder/70-portal.md) | **门户**：标准工作台、业务入口、指标、图表、视图组件、发布 |
+| [reference/builder/80-buttons-associated-resources.md](./reference/builder/80-buttons-associated-resources.md) | **关联资源 / 非主链路按钮维护**：关联视图/报表、`match_mappings`、上下文传参；按钮配置看视图文档 `action_buttons`；创建自定义按钮前先 `button get --button-text` 查重复用 |
+| [reference/builder/90-workflow.md](./reference/builder/90-workflow.md) | **流程**：WorkflowSpec、`patch_nodes`、角色/成员、流程回读 |
+| [reference/builder/99-publish-verify.md](./reference/builder/99-publish-verify.md) | **发布与回读**：`publish verify`、partial/readback 处理、最终汇报口径 |
+| [reference/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md) | **新建记录**：`record schema insert -> record insert --items-file`；成员/部门/关联优先自然语言输入；细节见 [record/insert](./reference/record/insert/README.md) |
+| [reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md) | **更新记录**：主链路是 `record get` → 智能体按 `fields[]` 组 key/value → **`record update`**；`record schema update` 仅用于失败后诊断可写字段/路径                                                                                                                                 |
+| [reference/QINGFLOW_CLI_RECORD_DELETE_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_DELETE_WORKFLOW.md) | **删除记录**：`record list/get` 精确定位 → `record delete --app-key --record-id --view-id system:*`；批量用 `--record-ids-file` |
+| [reference/record/analysis/README.md](./reference/record/analysis/README.md) | **数据分析**：最终统计结论、分析报告、趋势/排名/比例/分布统一走 `record access -> Python/pandas` |
+| [reference/builder/reference/app-delivery-sop.md](./reference/builder/reference/app-delivery-sop.md) | **底层交付参考**：历史完整 SOP、权限、系统列和工具细节；不是主入口 |
+| [reference/builder/reference/workspace-icons.md](./reference/builder/reference/workspace-icons.md) | **图标参考**：`builder icon catalog`；新建应用包、应用、门户必须显式选择非 `template` 的 `icon + color` |
+| [reference/builder/reference/match-rules.md](./reference/builder/reference/match-rules.md) | **统一筛选 / 条件写法**：`filters`、`visible_when`、QingBI 图表筛选、工作流条件、`match_mappings`、`field_mappings` 的 `operator/value` 规则 |
+| [reference/builder/workflow/README.md](./reference/builder/workflow/README.md) | **工作流搭建**：已有应用的流程建模、节点配置、`builder flow apply` 与 `patch_nodes` |
+| [reference/builder/code-integrations/README.md](./reference/builder/code-integrations/README.md) | **代码块 / Q-Linker 配置**：字段别名、绑定、输入字段插入和配置排障 |
+| [reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./reference/core/QINGFLOW_CLI_ADMIN_CHEATSHEET.md)       | **管理员**：检索、导入等与成员差异（主技能正文不展开）                                                                                                                                                                                                                                                         |
+| [reference/QINGFLOW_CLI_EXPLORATION_REPORT.md](./reference/core/QINGFLOW_CLI_EXPLORATION_REPORT.md)   | CLI 实测与 argparse/服务端对齐备忘                                                                                                                                                                                                                                                              |
+| [reference/QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md](./reference/core/QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md) | **可选**：全角色「一次可复制」分项模板；默认执行技能**不必**打开                                                                                                                                                                                                                                                  |
+| [scripts/find-app-by-keyword.py](./scripts/find-app-by-keyword.py)                               | **旧版 CLI 兼容脚本**：当 `app list --query` 不可用时，用 `app list` 本地解析；默认优先使用 `qingflow --json app list --query <关键词>`                                                                                                                                                                          |
+| [scripts/builder-package-from-app-list.py](./scripts/builder-package-from-app-list.py)           | **旧版 CLI 兼容脚本**：当 `builder package list` 不可用时，才从 `app list` 曲线反查 **`package_name` / `resolve-id`**；新版默认直接用 `qingflow --json builder package list --query <关键词>`                                                                                                                    |
 ## CLI 执行与 JSON 落盘
 
 1. 已知业务目标时直接执行目标命令，不固定前置 `auth whoami`、`workspace get` 或 `workspace select`。只有业务命令明确返回未登录、会话失效或工作区错误后，才恢复上下文并重试原命令。

package/skills/qingflow-cli/reference/builder/50-views.md

@@ -377,6 +377,16 @@ CLI 将参数与文件内容拼装为服务层载荷，**顶层键**如下：
 - `card`：必须配置 `detail`，并在卡片行操作明确时配置 `list`；核心操作视图不要只给 `header`。
 - `gantt`：不适合作为唯一核心操作视图；需要快捷按钮时同时提供配套 table/board 视图，在该操作视图中配置 `list` 和 `detail`。
 
+### 6.4.1 绑定已有自定义按钮（`buttons`，查重优先）
+
+视图声明里的 `buttons[]` 只做绑定（引用应用级自定义按钮的 `button_id`），不会创建按钮本体。绑定前必须查重，不要重复创建同名按钮：
+
+1. **查询**：`qingflow --json builder button get --app-key APP --button-text 按钮文案`（MCP `app_get_buttons` 传 `button_text`），按文案精确匹配。
+2. **有则复用**：唯一命中 → 取返回的 `button_id` 直接写进 `buttons[]`；同名多个 → 用 `button_id` 精确指定（避免歧义）。
+3. **没有再创建**：`builder button apply` 创建（其自身也按文案去重），拿到 `button_id` 后回到视图声明绑定。
+
+按钮本体维护（样式/跨视图复用/删除本体）见 [80-buttons-associated-resources.md](./80-buttons-associated-resources.md)。
+
 ### 6.5 关联视图/报表
 
 新版默认不要通过 `app_views_apply.associated_resources` 配置关联资源。应用级关联资源池和视图展示开关统一走 **`app_associated_resources_apply`** / CLI **`builder associated-resource apply`**。
@@ -510,6 +520,8 @@ qingflow builder views apply \
 | 现象 | 处理 |
 |------|------|
 | 列校验失败 / 无有效业务列 | **`app get fields`** 核对 **`name`**；避免 `columns` 仅含 **§7.1 系统列** |
+| 响应含 **`STALE_FIELD_REFERENCE`** / **`STALE_OPTION_REFERENCE`** 警告 | 声明引用了表单中已删除的字段/选项(后端保存视图本就原样透传);apply 已照写并在 `warnings` 留痕,重放/迁移场景属预期,人工整理时再清理死引用 |
+| 系统字段作标题/时间轴 | `title_que_id`/甘特 `start_que_id` 等可直接用系统字段 id(如 2=提交时间),与 `columns` 系统列同规则 |
 | 重名视图 / 删错 | **`app get views`**；更新时带 **`view_key`** |
 | 过滤器未生效疑虑 | 看响应 **`verification.view_filters_verified`**；必要时再 **`app get views`** |
 | 查询条件未生效疑虑 | 看响应 **`verification.view_query_conditions_verified`**；不要把 `query_conditions` 当 `filters` |

package/skills/qingflow-cli/reference/builder/80-buttons-associated-resources.md

@@ -23,6 +23,7 @@ app get -> app get views/charts/buttons/associated resources -> apply button or
 
 ## Custom buttons
 
+- **查重优先（硬规则）**：创建任何自定义按钮前，先 `builder button get --app-key APP --button-text 文案`（MCP `app_get_buttons` 传 `button_text`）按文案精确查重。唯一命中 → 直接复用其 `button_id`，不要创建；未命中 → 再走 `builder button apply` 创建（apply 本身也按 `button_text` 去重：无 `button_id` 时唯一同名匹配会转为更新，双保险）；同名多个 → 必须传 `button_id` 精确指定。禁止每次都新建同名按钮。
 - For normal view-level business actions, prefer `builder views apply` with `action_buttons`.
 - Use this standalone button tool for advanced cases: deleting button bodies, reusing the same button across many views, bulk reordering bindings, changing style independently, or configuring qRobot/wings when the user provides exact config.
 - Use `upsert_buttons` for create/update and `patch_buttons` for small changes.
@@ -44,6 +45,7 @@ Start from user intent:
 | Need | Preferred path |
 | --- | --- |
 | Create or patch a normal business button on one view | `builder views apply` with `action_buttons` |
+| 查询/查重已有自定义按钮 | `builder button get --app-key APP --button-text 文案`（唯一命中复用其 `button_id`） |
 | Set style, icon, cross-view reuse, remove button body, reorder bindings | `builder button apply` |
 | Add qRobot/wings behavior | `builder button apply`, only with user-provided exact config |
 | Clear a view's custom button bindings | `builder button apply` with `view_configs[].mode="replace"` and `buttons: []` |

package/src/qingflow_mcp/app_form_validator.py

@@ -11,9 +11,15 @@ from .app_form_compat import normalize_app_form_declaration
 from .builder_facade.app_form_schema import AppFormContractError, compact_schema_errors, schema_error_message
 
 
+#: code_block / q_linker 输出目标字段类型。后端写链无类型白名单(FormSvcImpl
+#: 原样落库),运行时 DataSvcImpl.getAnswerValueByString:选项/数字/日期有专门
+#: 分支;attachment 按拆分 URL 写入(专门分支);subtable 整表组装(专门分支);
+#: rich_text/data_relation 走 Question.canImport 兜底按字符串写入(不报错)。
+#: 四者为存量合法配置(提取读得出、apply 必须写回,两闸门同口径)。
 _INTEGRATION_OUTPUT_TARGET_FIELD_TYPES = {
     "text",
     "long_text",
+    "rich_text",
     "number",
     "amount",
     "date",
@@ -21,6 +27,9 @@ _INTEGRATION_OUTPUT_TARGET_FIELD_TYPES = {
     "single_choice",
     "single_select",
     "multi_select",
+    "attachment",
+    "data_relation",
+    "subtable",
 }
 _Q_LINKER_TEMPLATE_RE = re.compile(r"\{\{(?P<key>[^{}\s]+)\}\}")
 _FORMULA_IDENTIFIER_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
@@ -230,13 +239,20 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
                 if isinstance(field, dict):
                     top_fields.append((f"{row_path}/{field_index}", field))
     def resolve_local_selector(selector: Any) -> tuple[str, tuple[str, dict[str, Any]] | None]:
-        """Resolve against the declared body, preserving backend-dependent ID-only cases."""
+        """Resolve against the declared body, preserving backend-dependent ID-only cases.
+
+        返回态:resolved(唯一定位)/ invalid(定位失败)/ ambiguous(方案 A:name-only
+        命中多个同名字段,调用方须报 AMBIGUOUS_FIELD_SELECTOR)/ unknown(存在未命名
+        字段,后端侧再判)/ schema(结构不完整,交给 Schema 校验)。
+        """
         if not isinstance(selector, dict):
             return "schema", None
         raw_que_id = selector.get("queId")
         que_id = raw_que_id if isinstance(raw_que_id, int) and not isinstance(raw_que_id, bool) else None
         raw_name = selector.get("name")
-        name = raw_name if isinstance(raw_name, str) and raw_name else ""
+        # name 两侧 strip:存量字段名带前导/尾随空格,queId 已同时给出不构成歧义
+        # (与 compiler 侧三个 resolve 函数同口径)。
+        name = raw_name.strip() if isinstance(raw_name, str) and raw_name.strip() else ""
         if raw_que_id is not None and que_id is None:
             return "schema", None
         if raw_name is not None and not name:
@@ -245,21 +261,38 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
             matches = [(path, field) for path, field in top_fields if field.get("queId") == que_id]
             if len(matches) != 1:
                 return "invalid", None
-            declared_name = str(matches[0][1].get("name") or "")
+            declared_name = str(matches[0][1].get("name") or "").strip()
             if name and declared_name and name != declared_name:
                 return "invalid", None
             return "resolved", matches[0]
         if name:
-            matches = [(path, field) for path, field in top_fields if str(field.get("name") or "") == name]
+            matches = [(path, field) for path, field in top_fields if str(field.get("name") or "").strip() == name]
             if len(matches) == 1:
                 return "resolved", matches[0]
             if len(matches) > 1:
-                return "invalid", None
+                return "ambiguous", None
             if any(not str(field.get("name") or "") for _, field in top_fields):
                 return "unknown", None
             return "invalid", None
         return "schema", None
 
+    def ambiguity_message(selector: Any, subject: str) -> str:
+        name = str((selector or {}).get("name") or "").strip()
+        candidate_ids = sorted(
+            {
+                field.get("queId")
+                for _, field in top_fields
+                if str(field.get("name") or "").strip() == name
+                and isinstance(field.get("queId"), int)
+                and not isinstance(field.get("queId"), bool)
+            }
+        )
+        return (
+            f"AMBIGUOUS_FIELD_SELECTOR: {subject} name {name!r} matches multiple fields "
+            f"(candidate queIds: {candidate_ids}); duplicate names are allowed but "
+            "selectors must use queId to disambiguate"
+        )
+
     title_selector = spec.get("dataTitleField")
     if top_fields:
         if "dataTitleField" not in spec and "appKey" in payload:
@@ -271,6 +304,8 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
             # 显式 selector。
             if "appKey" not in payload:
                 errors.append(("/spec/dataTitleField", "dataTitleField must resolve to exactly one top-level field"))
+        elif resolve_local_selector(title_selector)[0] == "ambiguous":
+            errors.append(("/spec/dataTitleField", ambiguity_message(title_selector, "dataTitleField")))
         elif resolve_local_selector(title_selector)[0] == "invalid":
             errors.append(("/spec/dataTitleField", "dataTitleField must resolve to exactly one top-level field"))
     elif title_selector is not None:
@@ -279,11 +314,15 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
     cover_selector = spec.get("dataCoverField")
     if cover_selector is not None:
         cover_resolution, cover = resolve_local_selector(cover_selector)
-        if cover_resolution == "invalid":
+        if cover_resolution == "ambiguous":
+            errors.append(("/spec/dataCoverField", ambiguity_message(cover_selector, "dataCoverField")))
+        elif cover_resolution == "invalid":
             errors.append(("/spec/dataCoverField", "dataCoverField must resolve to exactly one top-level field"))
         elif cover_resolution == "resolved" and cover is not None and _field_type(cover[1]) != "attachment":
             errors.append(("/spec/dataCoverField", "dataCoverField must select a top-level attachment field"))
-    names: dict[str, str] = {}
+    # 方案 A(duplicate-field-name):同父级允许同名(后端以 queId 为身份,40013
+    # 实测 1624 组),不再报 duplicate name;歧义在 selector 解析处以
+    # AMBIGUOUS_FIELD_SELECTOR 显式拒绝。
     fields_by_id = {
         field.get("queId"): field
         for _, field in top_fields
@@ -291,12 +330,6 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
     }
     output_targets: dict[str, tuple[str, str]] = {}
     for path, field in top_fields:
-        name = str(field.get("name") or "")
-        if name:
-            if name in names:
-                errors.append((f"{path}/name", f"duplicate top-level field name; first declared at {names[name]}"))
-            else:
-                names[name] = f"{path}/name"
         field_type = _field_type(field)
         if field_type == "data_relation":
             config = field.get("config") if isinstance(field.get("config"), dict) else {}
@@ -342,6 +375,9 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
             selector = item.get("field") if isinstance(item.get("field"), dict) else {}
             input_path = f"{path}/config/{binding_name}/inputs/{index}"
             resolution, selected = resolve_local_selector(selector)
+            if resolution == "ambiguous":
+                errors.append((f"{input_path}/field", ambiguity_message(selector, f"{binding_name}.inputs[{index}].field")))
+                continue
             if resolution == "invalid":
                 errors.append((f"{input_path}/field", "input field must resolve to exactly one top-level field"))
                 continue
@@ -393,13 +429,16 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
                         )
                     )
 
-        producer = name or str(field.get("queId") or field_type)
+        producer = str(field.get("name") or "") or str(field.get("queId") or field_type)
         for index, item in enumerate(binding.get("outputs") or []):
             if not isinstance(item, dict):
                 continue
             selector = item.get("targetField")
             target_path = f"{path}/config/{binding_name}/outputs/{index}/targetField"
             resolution, selected = resolve_local_selector(selector)
+            if resolution == "ambiguous":
+                errors.append((target_path, ambiguity_message(selector, f"{binding_name}.outputs[{index}].targetField")))
+                continue
             if resolution == "invalid":
                 errors.append((target_path, "targetField must resolve to exactly one top-level field"))
                 continue

package/src/qingflow_mcp/builder_facade/app_form.py

@@ -18,6 +18,7 @@ from ..tools.app_tools import AppTools
 from ..tools.package_tools import PackageTools
 from .app_form_schema import AppFormContractError, AppFormSchemaContext, AppFormSchemaRegistry
 from .service import (
+    AmbiguousFieldSelector,
     _coerce_any_int,
     _compile_code_block_binding_fields,
     _compile_q_linker_binding_fields,
@@ -722,14 +723,26 @@ class AppFormNormalizer:
                 ]
                 if fields:
                     body.append({"kind": "row", "fields": fields})
+        # 空表单 + 悬空 dataTitleQueId/dataCoverQueId(模板安装出的空壳应用常见:
+        # 后端 GET 原样吐出指向已不存在字段的 id)读面 canonical 化为 null——
+        # 写回 null 后端 normalizeDataTitleQueId 兜底、空表单落库等价,避免
+        # validate/apply 的 INVALID_DATA_TITLE_FIELD 拒掉自家写面(round-trip 断裂)。
+        has_fields = any(
+            bool(block.get("fields")) for block in body if block.get("kind") == "row"
+        ) or any(
+            bool(row.get("fields"))
+            for block in body
+            if block.get("kind") == "section"
+            for row in block.get("rows") or []
+        )
         resource = {
             "apiVersion": context.api_version,
             "appKey": app_key,
             "spec": {
                 "appName": _compat_label(form.get("formTitle"), "App", app_key),
                 "appDescription": form.get("formDesc") or None,
-                "dataTitleField": _selector(title_id, field_names.get(title_id or 0)) if title_id is not None else None,
-                "dataCoverField": _selector(cover_id, field_names.get(cover_id or 0)) if cover_id is not None else None,
+                "dataTitleField": _selector(title_id, field_names.get(title_id or 0)) if title_id is not None and has_fields else None,
+                "dataCoverField": _selector(cover_id, field_names.get(cover_id or 0)) if cover_id is not None and has_fields else None,
                 "attachments": self._attachments(form.get("formAttach")),
                 "serialNumber": self._serial_number(form.get("serialNumType"), form.get("serialNumConfig")),
                 "body": body,
@@ -1743,6 +1756,8 @@ class AppFormCompiler:
             relation_context["questionRelations"] = relations
             internal_fields, relations = _compile_q_linker_binding_fields(fields=internal_fields, current_schema=relation_context)
             self._validate_unique_relation_targets(relations, internal_fields)
+        except AmbiguousFieldSelector as error:
+            raise AppFormFailure("AMBIGUOUS_FIELD_SELECTOR", str(error), "CONTRACT_PRECHECK", details={"candidateQueIds": error.candidates}) from error
         except (KeyError, ValueError) as error:
             raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", str(error), "CONTRACT_PRECHECK") from error
         self._assign_subfield_temp_ids(internal_fields)
@@ -2073,20 +2088,15 @@ class AppFormCompiler:
     ) -> tuple[JSONObject | None, JSONObject | None]:
         body = spec.get("body") or []
         fields = list(_iter_fields(body))
-        names: set[str] = set()
+        # 方案 A(duplicate-field-name):同父级允许同名——后端以 queId 为字段身份
+        # (40013 实测 1624 组同名),get 提出的合法形态必须能写回;name 解析的
+        # 歧义由各 selector resolver 以 AMBIGUOUS_FIELD_SELECTOR 显式拒绝,
+        # 不在目标校验层做 name 唯一性强校验。
         for field in fields:
-            name = str(field.get("name") or "")
-            if name in names:
-                raise AppFormFailure("DUPLICATE_FIELD_NAME", f"duplicate top-level field name: {name}", "CONTRACT_PRECHECK")
-            names.add(name)
             if _field_type(field) == "subtable":
-                sub_names: set[str] = set()
                 for subfield in field.get("subfields") or []:
                     if _field_type(subfield) not in SUBFIELD_TYPES:
                         raise AppFormFailure("INVALID_SPEC", "unsupported subtable field type", "CONTRACT_PRECHECK", details={"allowedTypes": sorted(SUBFIELD_TYPES)})
-                    if subfield.get("name") in sub_names:
-                        raise AppFormFailure("DUPLICATE_FIELD_NAME", f"duplicate subtable field name: {subfield.get('name')}", "CONTRACT_PRECHECK")
-                    sub_names.add(str(subfield.get("name") or ""))
         title_selector = spec.get("dataTitleField")
         data_title: JSONObject | None = None
         if fields:
@@ -2145,6 +2155,8 @@ class AppFormCompiler:
             relation_context["questionRelations"] = relations
             internal_fields, relations = _compile_q_linker_binding_fields(fields=internal_fields, current_schema=relation_context)
             self._validate_unique_relation_targets(relations, internal_fields)
+        except AmbiguousFieldSelector as error:
+            raise AppFormFailure("AMBIGUOUS_FIELD_SELECTOR", str(error), "COMPILE", details={"candidateQueIds": error.candidates}) from error
         except (KeyError, ValueError) as error:
             raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", str(error), "COMPILE") from error
         self._assign_subfield_temp_ids(internal_fields)
@@ -2626,8 +2638,7 @@ class AppFormCompiler:
 
     def _reference_config(self, profile: str, config: JSONObject, template: JSONObject | None = None) -> JSONObject:
         target_app_key = str(config.get("targetAppKey") or "")
-        target_form = self._read_form(profile, target_app_key, being_draft=False)
-        candidates = _backend_question_candidates(target_form)
+        candidates, _target_form = self._target_form_candidates(profile, target_app_key)
         explicit_display = isinstance(config.get("displayFields"), list)
         deprecated_keys = [
             key
@@ -2714,8 +2725,7 @@ class AppFormCompiler:
         target_app_key = str(relation.get("targetAppKey") or "")
         if not target_app_key:
             raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", "select scope relation requires targetAppKey", "COMPILE")
-        target_form = self._read_form(profile, target_app_key, being_draft=False)
-        candidates = _backend_question_candidates(target_form)
+        candidates, target_form = self._target_form_candidates(profile, target_app_key)
         displayed = _resolve_backend_selector(relation.get("displayedField") or {}, candidates, "selectScopeRelation.displayedField")
         payload: JSONObject = {
             "queId": _positive_int(internal.get("que_id")) or int(internal.get("que_temp_id") or 0),
@@ -2737,14 +2747,27 @@ class AppFormCompiler:
     def _resolve_subfield_runtime_id(selector: JSONObject, internal_fields: list[JSONObject], location: str) -> int:
         if not isinstance(selector, dict):
             raise AppFormFailure("INVALID_FIELD_SELECTOR", f"{location} must be an object", "COMPILE")
+        # 同 _resolve_backend_selector:name 两侧 strip(存量字段名带前后空格,queId 兜底唯一性)。
         que_id = _positive_int(selector.get("queId"))
-        name = str(selector.get("name") or "")
+        name = str(selector.get("name") or "").strip()
         matches = [
             item for item in internal_fields
             if (que_id is None or _positive_int(item.get("que_id")) == que_id)
-            and (not name or str(item.get("name") or "") == name)
+            and (not name or str(item.get("name") or "").strip() == name)
         ]
         if len(matches) != 1:
+            if que_id is None and matches:
+                raise AppFormFailure(
+                    "AMBIGUOUS_FIELD_SELECTOR",
+                    f"{location} matches multiple subfields with the same name; use queId to disambiguate",
+                    "COMPILE",
+                    details={
+                        "selector": selector,
+                        "candidateQueIds": sorted(
+                            {_positive_int(item.get("que_id")) or 0 for item in matches}
+                        ),
+                    },
+                )
             raise AppFormFailure("INVALID_FIELD_SELECTOR", f"{location} must resolve to exactly one subfield", "COMPILE", details={"selector": selector, "matches": len(matches)})
         return _positive_int(matches[0].get("que_id")) or int(matches[0].get("que_temp_id") or 0)
 
@@ -2796,8 +2819,7 @@ class AppFormCompiler:
             source_fields = available_internal_fields
             source_fields_are_backend = False
             if source.get("kind") == "app":
-                target_form = self._read_form(profile, str(source.get("appKey") or ""), being_draft=False)
-                source_fields = _backend_question_candidates(target_form)
+                source_fields, _target_form = self._target_form_candidates(profile, str(source.get("appKey") or ""))
                 source_fields_are_backend = True
                 target = _resolve_backend_selector(source.get("field") or {}, source_fields, "source.field")
                 relation.update(
@@ -3237,6 +3259,34 @@ class AppFormCompiler:
             raise AppFormFailure("FORM_READ_FAILED", "backend returned an invalid form", "READ")
         return value
 
+    def _target_form_candidates(self, profile: str, app_key: str) -> tuple[list[JSONObject], JSONObject]:
+        """跨表引用解析候选集:目标表 草稿∪发布 并集(queId 为 key,草稿覆盖)。
+
+        后端写链对跨表 queId(referQuestions/displayedQueId/matchRules 源字段)无
+        存在性校验、原样落库(FormSvcImpl.updateFormInfo);链上唯一读目标字段的
+        Formula.matchRulesToFormula 取 question∪draft_question 且草稿覆盖,编辑器
+        候选接口(/question/{appKey}/relation)同样支持 beingDraft 草稿态。get 按
+        草稿姿态提取声明,apply 只读发布会漏掉目标表「只加在草稿、从未发布」的字段
+        (round-trip 断裂);只读草稿又会漏掉发布后草稿里删掉的旧字段——并集与
+        后端写链语义一致。草稿读失败(目标表无草稿等)退回仅发布态。
+        """
+        draft_form: JSONObject = {}
+        try:
+            draft_form = self._read_form(profile, app_key, being_draft=True)
+        except AppFormFailure:
+            draft_form = {}
+        published_form = self._read_form(profile, app_key, being_draft=False)
+        merged: list[JSONObject] = []
+        seen: set[int] = set()
+        for item in [*_backend_question_candidates(draft_form), *_backend_question_candidates(published_form)]:
+            que_id = _positive_int(item.get("queId"))
+            if que_id is not None:
+                if que_id in seen:
+                    continue
+                seen.add(que_id)
+            merged.append(item)
+        return merged, (draft_form or published_form)
+
 
 class AppFormReconciler:
     RUNTIME_VERSION = "v1alpha1"
@@ -4395,33 +4445,46 @@ def _snake_code_block(value: JSONObject) -> JSONObject:
 
 
 def _backend_question_candidates(form: JSONObject) -> list[JSONObject]:
+    """目标表字段的解析候选集(含表格子字段及其「父表·子字段」前缀变体)。
+
+    遍历与后端对齐:FormSvcImpl.fillMatchRulesList 按 supId 全局解析父表标题、
+    不看容器嵌套层级,FormQuestionSvcImpl 的候选集同样把段落内字段展开——因此
+    表格(queType=18)无论位于 formQues 顶层、baseQues 还是段落(queType=24)
+    内部,其 subQuestions 都是合法候选;段落本身不作为候选。
+    """
     result: list[JSONObject] = []
+
+    def _visit(item: JSONObject) -> None:
+        que_type = _positive_int(item.get("queType"))
+        if que_type == 24:
+            for inner in item.get("innerQuestions") or []:
+                for nested in inner if isinstance(inner, list) else []:
+                    if isinstance(nested, dict):
+                        _visit(nested)
+            return
+        result.append(item)
+        # 表格(queType=18)子字段同样是合法的目标字段:后端 data_relation
+        # 运行时按 queId 解析目标字段并把表格子字段纳入 targetQuestionMap
+        # (DataRelationCalService 先按 queId 查 question、再把表格的
+        # subQuestions 合入)。displayedQueId 指向表格子字段是存量合法
+        # 配置,提取能读出、编译必须能写回(两闸门同口径)。
+        # matchRules 的筛选源字段(sourceField)在存量里带父表名前缀
+        # (「父表·子字段」,_data_relation_field_name 按同形态写回)。
+        if que_type == 18:
+            table_title = str(item.get("queTitle") or "")
+            for sub in item.get("subQuestions") or []:
+                if isinstance(sub, dict):
+                    prefixed = dict(sub)
+                    prefixed["_sup_que_title"] = table_title
+                    result.append(prefixed)
+
     for item in form.get("baseQues") or []:
         if isinstance(item, dict):
-            result.append(item)
+            _visit(item)
     for row in form.get("formQues") or []:
         for item in row if isinstance(row, list) else []:
-            if not isinstance(item, dict):
-                continue
-            if _positive_int(item.get("queType")) == 24:
-                for inner in item.get("innerQuestions") or []:
-                    result.extend(nested for nested in inner if isinstance(inner, list) and isinstance(nested, dict))
-            else:
-                result.append(item)
-                # 表格(queType=18)子字段同样是合法的目标字段:后端 data_relation
-                # 运行时按 queId 解析目标字段并把表格子字段纳入 targetQuestionMap
-                # (DataRelationCalService 先按 queId 查 question、再把表格的
-                # subQuestions 合入)。displayedQueId 指向表格子字段是存量合法
-                # 配置,提取能读出、编译必须能写回(两闸门同口径)。
-                # matchRules 的筛选源字段(sourceField)在存量里带父表名前缀
-                # (「父表·子字段」,_data_relation_field_name 按同形态写回)。
-                if _positive_int(item.get("queType")) == 18:
-                    table_title = str(item.get("queTitle") or "")
-                    for sub in item.get("subQuestions") or []:
-                        if isinstance(sub, dict):
-                            prefixed = dict(sub)
-                            prefixed["_sup_que_title"] = table_title
-                            result.append(prefixed)
+            if isinstance(item, dict):
+                _visit(item)
     return result
 
 
@@ -4451,29 +4514,58 @@ def _backend_selector_titles(item: JSONObject) -> list[str]:
 
 
 def _resolve_backend_selector(selector: JSONObject, candidates: list[JSONObject], location: str) -> JSONObject:
+    # name 比较两侧 strip:存量字段名带前导/尾随空格(后端无空白校验),声明里的
+    # name 与候选 queTitle 一个空格即失配;queId 已同时给出,空格差异不构成歧义。
     que_id = _positive_int(selector.get("queId"))
-    name = str(selector.get("name") or "")
+    name = str(selector.get("name") or "").strip()
     matches = [
         item
         for item in candidates
         if (que_id is None or _positive_int(item.get("queId")) == que_id)
-        and (not name or name in _backend_selector_titles(item))
+        and (not name or name in {title.strip() for title in _backend_selector_titles(item)})
     ]
     if len(matches) != 1:
+        # 方案 A:后端允许同父级同名(queId 为身份)。name-only 命中多个时显式报
+        # 歧义并给出候选 queId,禁止静默取第一个。
+        if que_id is None and matches:
+            raise AppFormFailure(
+                "AMBIGUOUS_FIELD_SELECTOR",
+                f"{location} matches multiple fields with the same name; use queId to disambiguate",
+                "CONTRACT_PRECHECK",
+                details={
+                    "selector": selector,
+                    "candidateQueIds": sorted(
+                        {_positive_int(item.get("queId")) or 0 for item in matches}
+                    ),
+                },
+            )
         raise AppFormFailure("INVALID_FIELD_SELECTOR", f"{location} must resolve to exactly one field", "CONTRACT_PRECHECK", details={"selector": selector, "matches": len(matches)})
     return matches[0]
 
 
 def _resolve_canonical_selector(selector: JSONObject, candidates: list[JSONObject], location: str) -> JSONObject:
+    # 同 _resolve_backend_selector:name 两侧 strip(存量字段名带前后空格,queId 兜底唯一性)。
     que_id = _positive_int(selector.get("queId"))
-    name = str(selector.get("name") or "")
+    name = str(selector.get("name") or "").strip()
     matches = [
         item
         for item in candidates
         if (que_id is None or _positive_int(item.get("queId")) == que_id)
-        and (not name or str(item.get("name") or "") == name)
+        and (not name or str(item.get("name") or "").strip() == name)
     ]
     if len(matches) != 1:
+        if que_id is None and matches:
+            raise AppFormFailure(
+                "AMBIGUOUS_FIELD_SELECTOR",
+                f"{location} matches multiple fields with the same name; use queId to disambiguate",
+                "CONTRACT_PRECHECK",
+                details={
+                    "selector": selector,
+                    "candidateQueIds": sorted(
+                        {_positive_int(item.get("queId")) or 0 for item in matches}
+                    ),
+                },
+            )
         raise AppFormFailure(
             "INVALID_FIELD_SELECTOR",
             f"{location} must resolve to exactly one top-level field",
@@ -4484,14 +4576,27 @@ def _resolve_canonical_selector(selector: JSONObject, candidates: list[JSONObjec
 
 
 def _resolve_internal_selector(selector: JSONObject, fields: list[JSONObject], location: str) -> JSONObject:
+    # 同 _resolve_backend_selector:name 两侧 strip(存量字段名带前后空格,queId 兜底唯一性)。
     que_id = _positive_int(selector.get("queId") or selector.get("que_id"))
-    name = str(selector.get("name") or "")
+    name = str(selector.get("name") or "").strip()
     matches = [
         item
         for item in fields
         if (que_id is None or _positive_int(item.get("que_id")) == que_id)
-        and (not name or str(item.get("name") or "") == name)
+        and (not name or str(item.get("name") or "").strip() == name)
     ]
     if len(matches) != 1:
+        if que_id is None and matches:
+            raise AppFormFailure(
+                "AMBIGUOUS_FIELD_SELECTOR",
+                f"{location} matches multiple fields with the same name; use queId to disambiguate",
+                "COMPILE",
+                details={
+                    "selector": selector,
+                    "candidateQueIds": sorted(
+                        {_positive_int(item.get("que_id")) or 0 for item in matches}
+                    ),
+                },
+            )
         raise AppFormFailure("INVALID_FIELD_SELECTOR", f"{location} must resolve to exactly one field", "COMPILE", details={"selector": selector, "matches": len(matches)})
     return matches[0]