@qingflow-tech/qingflow-cli 1.1.50 → 1.1.53

package/skills/qingflow-cli/reference/builder/README.md

@@ -38,7 +38,7 @@ Rules:
 - Portal chart sections use one `chart` field: `{"chart_id":"..."}` to reuse an existing QingBI chart, or `{"app_key":"...","name":"...","chart_type":"...",...}` to create/update the needed chart inline.
 - Buttons are part of the view design: declare them in the target view with `action_buttons`.
 - Update instructions live inside the resource document. Do not use `update-*` as a separate main route.
-- Batch read, batch write, and patch are resource-specific variants, not separate workflows.
+- Batch read, batch write, and patch are resource-specific variants, not separate workflows. View writes are single-operation: `builder views apply` handles one view per call; consult [50-views.md](./50-views.md) before preparing multiple view changes.
 
 ## File responsibilities
 

package/skills/qingflow-cli/reference/builder/reference/app-delivery-sop.md

@@ -41,7 +41,7 @@
 这些不是独立流程，而是读、写、改三个动作的多资源形态：
 
 - **批量读**：读多个应用时优先用 `--app-keys`，例如 `builder app get --app-keys a,b fields`、`builder app get --app-keys a,b views`、`builder button get --app-keys a,b`、`builder associated-resource get --app-keys a,b`、`builder publish verify --app-keys a,b`。读结果同时看成功项和 `errors[]`，不要因单个应用失败否定全批。
-- **批量写**：视图、按钮、关联资源和报表按各自资源契约使用对应的批量文件；应用表单不走 `apps-file`，而是每个应用独立提交完整 AppForm 声明。
+- **批量写**：仅在资源契约明确支持时使用批量文件；视图例外，`builder views apply` 每次只提交一个视图的一种操作，不支持多视图批量创建或把 upsert/patch/remove 混在一次调用中。应用表单不走 `apps-file`，而是每个应用独立提交完整 AppForm 声明。
 - **局部改**：只改已存在资源的少量参数时用对应 patch 文件；`patch_*` 内只写目标定位字段和 `set/unset`，不要用不完整 `upsert_*` 伪装局部更新。
 
 ---
@@ -201,8 +201,8 @@ qingflow builder schema apply \
 - 如果返回 `MULTI_APP_STATIC_VALIDATION_FAILED`，读取 `details.issues[]` 的 `path/error_code/fix_hint` 修 payload；这是写入前失败，通常可以修正后重试，不需要 readback。
 - 多应用 schema apply 不做事务回滚；如果部分失败，只补失败的 `apps[].row_number`，不要整批重复提交。
 - 这个模式只负责应用壳与字段；视图、按钮、关联资源、报表仍拿返回的 `app_key` 继续走各自 apply 工具。
-- `target_app_ref`、`as_data_title`、`display_field` 等只属于旧载荷。迁移时将关系改写为 AppForm `config.targetAppKey`、`config.displayField`、`config.visibleFields`，并使用已确认的真实 app key。
-- 历史 schema adapter 写入后可读 `details.relation_readback_matrix[]`：逐项核对旧 `target_app_key`、`relation_mode`、`display_field`、`visible_fields`。迁移到当前 AppForm 后，改为读取 draft/published form 的 `config.targetAppKey`、`config.relationMode`、`config.displayField`、`config.visibleFields`，不要提交旧 `update_fields` patch。
+- `target_app_ref`、`as_data_title`、`display_field` 等只属于旧载荷。迁移时将关系改写为 AppForm `config.targetAppKey`、`config.displayFields[]`（含 `auth`）、`config.twoWayBoundField`，并使用已确认的真实 app key。
+- 历史 schema adapter 写入后可读 `details.relation_readback_matrix[]`：逐项核对旧 `target_app_key`、`relation_mode`、`display_field`、`visible_fields`。迁移到当前 AppForm 后，改为读取 draft/published form 的 `config.targetAppKey`、`config.relationMode`、`config.twoWayBoundField`、`config.displayFields[]`，不要提交旧 `update_fields` patch。
 - 一个应用可以包含多个 `relation` 字段；不要因为 relation 数量超过 1 就降级成文本。若真实写入失败或 relation readback mismatch，只按实际错误和 `details.relation_repair_plan[]` 做最小修复。
 - 完整系统遇到超时、`partial_success`、`write_executed=true`、`safe_to_retry=false` 或 readback 不完整时，先按 §3.4 读回，不要直接拆成单应用创建。
 
@@ -349,7 +349,7 @@ qingflow builder flow apply \
 | **`address`** | 地址复合字段。 |
 | **`attachment`** | 附件。 |
 | **`boolean`** | 是否。 |
-| **`relation`** | 旧载荷使用 `target_app_key` / `target_app_ref`；当前 AppForm 使用 `config.targetAppKey`、`config.relationMode`、`config.displayField`、`config.visibleFields`。 |
+| **`relation`** | 旧载荷使用 `target_app_key` / `target_app_ref`；当前 AppForm 使用 `config.targetAppKey`、`config.relationMode`、`config.twoWayBoundField`、`config.displayFields[]`。 |
 | **`subtable`** | 当前 AppForm 使用 `subfields[]` 及 Schema 返回的 camelCase 配置；旧 `subfield_updates` 只作迁移线索。 |
 | **`q_linker`** | 当前 AppForm 使用 `config.qLinkerBinding`，其 `outputs[].targetField` 必须按字段 Schema 配置。 |
 | **`code_block`** | 当前 AppForm 使用 `config.codeBlockBinding`，其 `outputs[].targetField` 必须按字段 Schema 配置。 |
@@ -374,14 +374,14 @@ qingflow builder flow apply \
 
 后端很多保存接口仍是整份配置保存，但新版 CLI/MCP 对外提供 **public partial patch**：
 
-- 已有视图：`builder views apply --views-file`，其中对应项写 `operation: "patch"`
+- 已有视图：`builder views apply --app-key APP_KEY --patch-views-file PATH`，文件只放一项，写 `view_key`/`name` 与 `set`/`unset`
 - 已有按钮：`builder button apply --patch-buttons-file`
 - 已有关联资源：`builder associated-resource apply --patch-resources-file`
 - 已有报表：`builder charts apply --patch-file`
 - 已有流程节点：`builder flow apply --patch-nodes-file`
 - 已有门户组件：`builder portal apply --patch-sections-file`
 
-局部更新的语义是：你只写要替换的参数，工具内部读取当前配置、补齐后端必填字段，再整份保存。每个 patch 项直接使用对象真实定位字段 + `set` / 可选 `unset`，不要写字面量 `selector` key。示例：`{"operation":"patch","app_key":"APP_KEY","view_key":"VIEW_KEY","set":{"query_conditions":{...}}}`、`{"button_id": 1001, "set": {"button_text": "新名称"}}`、`{"associated_item_id": 123, "set": {"match_mappings": [...]}}`、`{"chart_id": 456, "set": {"name": "新报表名"}}`、`{"id": "node_1", "set": {"name": "主管审批"}}`、`{"chart": {"chart_key": "xxx"}, "set": {"rows": 7}}`。
+局部更新的语义是：你只写要替换的参数，工具内部读取当前配置、补齐后端必填字段，再整份保存。每个 patch 项直接使用对象真实定位字段 + `set` / 可选 `unset`，不要写字面量 `selector` key。示例：`{"view_key":"VIEW_KEY","set":{"query_conditions":{...}}}`、`{"button_id": 1001, "set": {"button_text": "新名称"}}`、`{"associated_item_id": 123, "set": {"match_mappings": [...]}}`、`{"chart_id": 456, "set": {"name": "新报表名"}}`、`{"id": "node_1", "set": {"name": "主管审批"}}`、`{"chart": {"chart_key": "xxx"}, "set": {"rows": 7}}`。
 
 `upsert_*` 用于创建或提供完整目标配置；不要只给 `name/type/query_conditions` 这类局部片段然后期待后端自动合并。
 

package/skills/qingflow-cli/reference/data/README.md

@@ -19,7 +19,7 @@
 
 ## 执行与恢复
 
-- 已知 `app_key` 时直接执行目标业务命令；只有业务命令明确报告会话或工作区错误后才恢复认证上下文。
+- 已知 `app_key` 时直接执行目标业务命令；只有应用名称时先用 `app list --query` 查找并核对 `app_name/title`，目标明确且唯一时取其 `app_key`，否则请用户确认。不能把名称传给 `--app-key`。只有业务命令明确报告会话或工作区错误后才恢复认证上下文。
 - 定位目标记录时先 query，再按需 get。字段只使用当前 schema 与字段能力允许的 id、能力和形状。
 - insert、update、delete 会改变真实业务数据。删除、覆盖已有值或批量写入前，必须确认目标和影响范围。
 - 返回后先检查 `write_executed`、`retry_safe`、字段错误和 hints。已执行、部分成功或状态不明时不得重放原请求。

package/skills/qingflow-cli/reference/examples/README.md

@@ -7,7 +7,7 @@ Use these files as copyable bases after reading the matching resource document.
 | Historical single-app schema probe | [schema/schema_single_app_form_standard.example.json](./schema/schema_single_app_form_standard.example.json) | Retired `--form-file` shape; use `builder app-form schema/get/validate/apply` for current declarations. |
 | Historical multi-app schema probe | [schema/schema_multi_app_form_relation_layout.example.json](./schema/schema_multi_app_form_relation_layout.example.json) | Retired `--apps-file` shape; current systems create independent AppForms and then bind confirmed app keys. |
 | Existing-app layout probe | [layout/layout_sections_full.example.json](./layout/layout_sections_full.example.json) | Historical layout-patch shape; current new and existing forms use the complete AppForm `spec.body`. |
-| Views | [views/views_upsert_table_minimal.example.json](./views/views_upsert_table_minimal.example.json), [views/views_batch_full.example.json](./views/views_batch_full.example.json) | `views[]` shape with filters, query panel, view-bound buttons, batch upsert/patch/remove. |
+| Views | [views/views_upsert_table_minimal.example.json](./views/views_upsert_table_minimal.example.json), [views/views_apply_v1alpha1.example.json](./views/views_apply_v1alpha1.example.json) | 单视图 JSON 对象，包含筛选、查询面板和视图绑定按钮；通过 `--app-key` 指定应用。 |
 | Charts | [charts/charts_upsert_dashboard_starter.example.json](./charts/charts_upsert_dashboard_starter.example.json) | Standalone chart apply; portal usually creates missing charts inline. |
 | Portal | [portal/portal_sections_standard_workbench.example.json](./portal/portal_sections_standard_workbench.example.json) | Standard workbench with inline QingBI charts and data views. |
 | Associated resources | [associated/associated_resources_semantic_full.example.json](./associated/associated_resources_semantic_full.example.json) | Current-record matching through `match_mappings`. |

package/skills/qingflow-cli/reference/examples/views/views_apply_v1alpha1.example.json

@@ -0,0 +1,14 @@
+{
+  "name": "项目台账视图",
+  "type": "table",
+  "columns": [100, 101, 102, 103],
+  "data_permission": {"type": "custom", "scope": "dept"},
+  "sort": [{"que_id": 100, "ascending": false}],
+  "display": {"row_height": "compact", "pin_navigate": true},
+  "query_conditions": {
+    "enabled": true,
+    "exact": false,
+    "hide_before_query": false,
+    "rows": [["项目名称", "负责人"], ["创建时间"]]
+  }
+}

package/skills/qingflow-cli/reference/examples/views/views_upsert_table_minimal.example.json

@@ -1,42 +1,36 @@
 {
-  "views": [
+  "name": "示例业务操作视图_CLI模板",
+  "type": "table",
+  "columns": [100, 101, 102, 103],
+  "filters": [
+    {"que_id": 100, "operator": "neq", "value": "已关闭"}
+  ],
+  "query_conditions": {
+    "enabled": true,
+    "exact": false,
+    "hide_before_query": false,
+    "rows": [["主记录编号", "主记录名称"], ["状态", "负责人"]]
+  },
+  "action_buttons": [
     {
-      "operation": "upsert",
-      "app_key": "APP_KEY",
-      "name": "示例业务操作视图_CLI模板",
-      "type": "table",
-      "columns": ["主记录编号", "主记录名称", "状态", "负责人"],
-      "filters": [
-        {"field_name": "状态", "operator": "neq", "value": "已关闭"}
+      "text": "行内创建子记录",
+      "action": "add_data",
+      "target_app_key": "TARGET_APP_KEY",
+      "field_mappings": [
+        {"source_field": "数据ID", "target_field": "关联主记录"}
       ],
-      "query_conditions": {
-        "enabled": true,
-        "exact": false,
-        "hide_before_query": false,
-        "rows": [["主记录编号", "主记录名称"], ["状态", "负责人"]]
-      },
-      "action_buttons": [
-        {
-          "text": "行内创建子记录",
-          "action": "add_data",
-          "target_app_key": "TARGET_APP_KEY",
-          "field_mappings": [
-            {"source_field": "数据ID", "target_field": "关联主记录"}
-          ],
-          "default_values": {"目标状态字段": "REPLACE_WITH_TARGET_OPTION_LABEL"},
-          "placement": "list"
-        },
-        {
-          "text": "详情创建子记录",
-          "action": "add_data",
-          "target_app_key": "TARGET_APP_KEY",
-          "field_mappings": [
-            {"source_field": "数据ID", "target_field": "关联主记录"}
-          ],
-          "default_values": {"目标状态字段": "REPLACE_WITH_TARGET_OPTION_LABEL"},
-          "placement": "detail"
-        }
-      ]
+      "default_values": {"目标状态字段": "REPLACE_WITH_TARGET_OPTION_LABEL"},
+      "placement": "list"
+    },
+    {
+      "text": "详情创建子记录",
+      "action": "add_data",
+      "target_app_key": "TARGET_APP_KEY",
+      "field_mappings": [
+        {"source_field": "数据ID", "target_field": "关联主记录"}
+      ],
+      "default_values": {"目标状态字段": "REPLACE_WITH_TARGET_OPTION_LABEL"},
+      "placement": "detail"
     }
   ]
 }

package/src/qingflow_mcp/app_form_compat.py

@@ -10,6 +10,9 @@ from .json_types import JSONObject
 TYPE_ALIASES = {
     "multiline": "long_text",
     "textarea": "long_text",
+    "richtext": "rich_text",
+    "rich-text": "rich_text",
+    "rich_text": "rich_text",
     "radio": "single_choice",
     "boolean": "single_choice",
     "select": "single_select",

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_]*")
@@ -218,19 +227,32 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
             widths = ["width" in field for field in fields if isinstance(field, dict)]
             if widths and any(widths) and not all(widths):
                 errors.append((row_path, "width must be present on every field in the row or omitted from all"))
-            if widths and all(widths) and sum(field.get("width", 0) for field in fields if isinstance(field, dict)) != 100:
-                errors.append((row_path, "field widths must total 100"))
+            # 行宽契约(与后端语义对齐):任意 1-100 整数 + 全有或全无。
+            # 后端 html_width 无取值/总和校验,存量存在 33/34 三等分与字段删除后
+            # 留白(如 3×25=75)的行;get 读出的原布局必须能原样过校验
+            # (apply(get(S)) ≡ S 命题的必要条件)。
+            if widths and all(widths):
+                bad = [f.get("width") for f in fields if isinstance(f, dict) and not (isinstance(f.get("width"), int) and 1 <= f["width"] <= 100)]
+                if bad:
+                    errors.append((row_path, "field widths must be an integer between 1 and 100"))
             for field_index, field in enumerate(fields):
                 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:
@@ -239,26 +261,52 @@ 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:
             pass
-        elif title_selector is None or resolve_local_selector(title_selector)[0] == "invalid":
+        elif title_selector is None:
+            # dataTitleField=null 仅在带 appKey 的更新/round-trip 场景放行:后端写链
+            # FormSvcImpl.normalizeDataTitleQueId 对 null 自动 fallback 到第一个可用
+            # 字段,get 读面在后端未设置时原样输出 null。创建场景(无 appKey)仍需
+            # 显式 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:
         errors.append(("/spec/dataTitleField", "dataTitleField must be null when body is empty"))
@@ -266,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
@@ -278,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 {}
@@ -329,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
@@ -380,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