@josephyan/qingflow-app-user-mcp 0.2.0-beta.94 → 0.2.0-beta.96

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-user-mcp@0.2.0-beta.94
+npm install @josephyan/qingflow-app-user-mcp@0.2.0-beta.96
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-user-mcp@0.2.0-beta.94 qingflow-app-user-mcp
+npx -y -p @josephyan/qingflow-app-user-mcp@0.2.0-beta.96 qingflow-app-user-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "0.2.0-beta.94",
+  "version": "0.2.0-beta.96",
   "description": "Operational end-user MCP for Qingflow records, tasks, comments, and directory workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "0.2.0b94"
+version = "0.2.0b96"
 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.0b94"
+_FALLBACK_VERSION = "0.2.0b95"
 
 
 def _resolve_local_pyproject_version() -> str | None:

package/src/qingflow_mcp/builder_facade/models.py

@@ -819,6 +819,10 @@ class FieldMutation(StrictModel):
         validation_alias=AliasChoices("custom_button_text", "customButtonText", "custom_btn_text", "customBtnText"),
     )
     subfields: list[FieldPatch] | None = None
+    subfield_updates: list["FieldUpdatePatch"] | None = Field(
+        default=None,
+        validation_alias=AliasChoices("subfield_updates", "subfieldUpdates"),
+    )
 
     @model_validator(mode="after")
     def validate_shape(self) -> "FieldMutation":
@@ -848,8 +852,12 @@ class FieldMutation(StrictModel):
             or self.custom_button_text is not None
         ):
             raise ValueError("code_block_config, code_block_binding, auto_trigger, custom_button_text_enabled, and custom_button_text are only allowed for code_block fields")
-        if self.type == PublicFieldType.subtable and not self.subfields:
-            raise ValueError("subtable field requires subfields")
+        if self.type == PublicFieldType.subtable and not self.subfields and not self.subfield_updates:
+            raise ValueError("subtable field requires subfields or subfield_updates")
+        if self.type is not None and self.type != PublicFieldType.subtable and self.subfield_updates:
+            raise ValueError("subfield_updates are only allowed for subtable fields")
+        if self.subfields and self.subfield_updates:
+            raise ValueError("subfields and subfield_updates cannot be used together")
         return self
 
     @model_validator(mode="before")
@@ -1536,6 +1544,8 @@ class PortalApplyRequest(StrictModel):
 
 
 FieldPatch.model_rebuild()
+FieldMutation.model_rebuild()
+FieldUpdatePatch.model_rebuild()
 
 
 class AppGetResponse(StrictModel):

package/src/qingflow_mcp/builder_facade/service.py

@@ -1,12 +1,16 @@
 from __future__ import annotations
 
+import base64
 from copy import deepcopy
 from dataclasses import dataclass, field
 import json
 import os
+import random
 import re
+import string
 import tempfile
 from typing import Any, cast
+from urllib.parse import quote_plus, unquote_plus
 from uuid import uuid4
 
 from ..backend_client import BackendRequestContext
@@ -143,6 +147,7 @@ JUDGE_EQUAL_ANY = 9
 JUDGE_FUZZY_MATCH = 19
 JUDGE_INCLUDE_ANY = 20
 DEFAULT_TYPE_RELATION = 2
+DEFAULT_TYPE_FORMULA = 3
 RELATION_TYPE_Q_LINKER = 2
 RELATION_TYPE_CODE_BLOCK = 3
 
@@ -4630,7 +4635,19 @@ class AiBuilderFacade:
                 )
             field = current_fields[matched]
             previous_name = field["name"]
-            _apply_field_mutation(field, patch.set)
+            try:
+                _apply_field_mutation(field, patch.set)
+            except ValueError as error:
+                return _failed(
+                    "VALIDATION_ERROR",
+                    str(error),
+                    normalized_args=normalized_args,
+                    details={
+                        "selector": patch.selector.model_dump(mode="json"),
+                        "app_key": target.app_key,
+                    },
+                    suggested_next_call={"tool_name": "app_get_fields", "arguments": {"profile": profile, "app_key": target.app_key}},
+                )
             current_fields[matched] = field
             layout = _rename_field_in_layout(layout, previous_name, field["name"])
             updated.append(field["name"])
@@ -10527,14 +10544,14 @@ def _parse_code_block_inputs_and_body(code_content: str) -> tuple[list[dict[str,
     return inputs, body
 
 
-def _compact_public_field_read(*, field: dict[str, Any], layout: dict[str, Any]) -> dict[str, Any]:
+def _compact_public_field_read(*, field: dict[str, Any], layout: dict[str, Any], nested: bool = False) -> dict[str, Any]:
     payload = {
         "field_id": field.get("field_id"),
         "que_id": field.get("que_id"),
         "name": field.get("name"),
         "type": field.get("type"),
         "required": bool(field.get("required")),
-        "section_id": _find_field_section_id(layout, str(field.get("name") or "")),
+        "section_id": None if nested else _find_field_section_id(layout, str(field.get("name") or "")),
     }
     if field.get("type") == FieldType.relation.value:
         payload["target_app_key"] = field.get("target_app_key")
@@ -10567,6 +10584,12 @@ def _compact_public_field_read(*, field: dict[str, Any], layout: dict[str, Any])
             payload["custom_button_text"] = field.get("custom_button_text")
         if field.get("metadata_unverified") is not None:
             payload["metadata_unverified"] = bool(field.get("metadata_unverified"))
+    if field.get("type") == FieldType.subtable.value:
+        payload["subfields"] = [
+            _compact_public_field_read(field=subfield, layout=layout, nested=True)
+            for subfield in cast(list[dict[str, Any]], field.get("subfields") or [])
+            if isinstance(subfield, dict)
+        ]
     return payload
 
 
@@ -10862,6 +10885,35 @@ def _code_block_binding_equal(left: Any, right: Any) -> bool:
     return _normalize_code_block_binding(left) == _normalize_code_block_binding(right)
 
 
+_SAFE_SUBFIELD_MUTATION_KEYS = frozenset({"name", "required", "description", "subfield_updates"})
+
+
+def _validate_safe_subfield_mutation(*, payload: dict[str, Any], location: str) -> None:
+    unsupported = sorted(key for key in payload if key not in _SAFE_SUBFIELD_MUTATION_KEYS)
+    if unsupported:
+        raise ValueError(
+            f"{location} only supports safe overlay keys: name, required, description, subfield_updates; "
+            f"unsupported keys: {', '.join(unsupported)}"
+        )
+
+
+def _apply_subfield_updates(field: dict[str, Any], raw_updates: list[Any]) -> None:
+    if str(field.get("type") or "") != FieldType.subtable.value:
+        raise ValueError("subfield_updates can only target subtable fields")
+    subfields = [subfield for subfield in cast(list[dict[str, Any]], field.get("subfields") or []) if isinstance(subfield, dict)]
+    for index, raw_item in enumerate(raw_updates):
+        patch = FieldUpdatePatch.model_validate(raw_item)
+        payload = patch.set.model_dump(mode="json", exclude_none=True)
+        _validate_safe_subfield_mutation(payload=payload, location=f"subfield_updates[{index}].set")
+        target = _resolve_field_selector_with_uniqueness(
+            fields=subfields,
+            selector_payload=patch.selector.model_dump(mode="json", exclude_none=True),
+            location=f"subfield_updates[{index}].selector",
+        )
+        _apply_field_mutation(target, patch.set)
+    field["subfields"] = subfields
+
+
 def _apply_field_mutation(field: dict[str, Any], mutation: Any) -> None:
     payload = mutation.model_dump(mode="json", exclude_none=True)
     relation_config_explicit = (
@@ -10930,6 +10982,8 @@ def _apply_field_mutation(field: dict[str, Any], mutation: Any) -> None:
     if "subfields" in payload:
         field["subfields"] = [_field_patch_to_internal(item) for item in payload["subfields"]]
         question_rebuild_required = True
+    if "subfield_updates" in payload:
+        _apply_subfield_updates(field, payload["subfield_updates"])
     if relation_config_explicit:
         field["_relation_config_explicit"] = True
         question_rebuild_required = True
@@ -12927,6 +12981,48 @@ def _copy_present_keys(
     return payload
 
 
+def _looks_like_backend_encoded_formula(value: str) -> bool:
+    if len(value) <= 32:
+        return False
+    encoded = value[16:-16]
+    if not encoded:
+        return False
+    try:
+        decoded = base64.b64decode(encoded, validate=True).decode("utf-8")
+        unquote_plus(decoded)
+    except Exception:
+        return False
+    return True
+
+
+def _encode_formula_for_backend_save(value: Any) -> Any:
+    if not isinstance(value, str) or not value:
+        return value
+    if _looks_like_backend_encoded_formula(value):
+        return value
+    encoded = quote_plus(value, encoding="utf-8")
+    b64_value = base64.b64encode(encoded.encode("utf-8")).decode("ascii")
+    alphabet = string.ascii_letters + string.digits
+    prefix = "".join(random.choice(alphabet) for _ in range(16))
+    suffix = "".join(random.choice(alphabet) for _ in range(16))
+    return f"{prefix}{b64_value}{suffix}"
+
+
+def _normalize_formula_defaults_for_save(value: Any) -> None:
+    if isinstance(value, list):
+        for item in value:
+            _normalize_formula_defaults_for_save(item)
+        return
+    if not isinstance(value, dict):
+        return
+    if _coerce_any_int(value.get("queDefaultType")) == DEFAULT_TYPE_FORMULA and value.get("queDefaultValue"):
+        value["queDefaultValue"] = _encode_formula_for_backend_save(value.get("queDefaultValue"))
+    for key in ("subQuestions", "innerQuestions"):
+        nested = value.get(key)
+        if isinstance(nested, (list, dict)):
+            _normalize_formula_defaults_for_save(nested)
+
+
 def _normalize_reference_question_for_save(value: Any, *, ordinal: int) -> dict[str, Any] | None:
     if not isinstance(value, dict):
         return None
@@ -13090,6 +13186,8 @@ def _normalize_question_relations_for_save(question_relations: list[dict[str, An
             value = relation.get(key)
             if value is None:
                 continue
+            if key == "matchRuleFormula":
+                value = _encode_formula_for_backend_save(value)
             item[key] = deepcopy(value)
         if item:
             normalized.append(item)
@@ -13099,22 +13197,32 @@ def _normalize_question_relations_for_save(question_relations: list[dict[str, An
 def _field_rename_maps(fields: list[dict[str, Any]]) -> tuple[dict[int, str], dict[str, str]]:
     by_que_id: dict[int, str] = {}
     by_title: dict[str, str] = {}
-    for field in fields:
+
+    def visit(field: dict[str, Any]) -> None:
         if not isinstance(field, dict):
-            continue
+            return
         template = field.get("_question_template")
         if not isinstance(template, dict):
-            continue
+            for subfield in cast(list[dict[str, Any]], field.get("subfields") or []):
+                visit(subfield)
+            return
         old_title = str(template.get("queTitle") or "").strip()
         new_title = str(field.get("name") or "").strip()
         if not old_title or not new_title or old_title == new_title:
-            continue
+            for subfield in cast(list[dict[str, Any]], field.get("subfields") or []):
+                visit(subfield)
+            return
         que_id = _coerce_nonnegative_int(field.get("que_id"))
         if que_id is None:
             que_id = _coerce_nonnegative_int(template.get("queId"))
         if que_id is not None:
             by_que_id[que_id] = new_title
         by_title[old_title] = new_title
+        for subfield in cast(list[dict[str, Any]], field.get("subfields") or []):
+            visit(subfield)
+
+    for field in fields:
+        visit(field)
     return by_que_id, by_title
 
 
@@ -13151,6 +13259,20 @@ def _sync_question_title_references(value: Any, *, by_que_id: dict[int, str], by
             _sync_question_title_references(child_value, by_que_id=by_que_id, by_title=by_title)
 
 
+def _materialize_preserved_subtable_question(field: dict[str, Any], *, template: dict[str, Any]) -> dict[str, Any] | None:
+    materialized_subquestions: list[dict[str, Any]] = []
+    for subfield in cast(list[dict[str, Any]], field.get("subfields") or []):
+        if not isinstance(subfield, dict):
+            continue
+        materialized = _materialize_preserved_question(subfield)
+        if materialized is None:
+            return None
+        materialized_subquestions.append(materialized)
+    template["subQuestions"] = materialized_subquestions
+    template["innerQuestions"] = [deepcopy(materialized_subquestions)]
+    return template
+
+
 def _materialize_preserved_question(field: dict[str, Any]) -> dict[str, Any] | None:
     template = deepcopy(field.get("_question_template"))
     if not isinstance(template, dict):
@@ -13163,6 +13285,8 @@ def _materialize_preserved_question(field: dict[str, Any]) -> dict[str, Any] | N
     if "description" in overlay_keys:
         description = field.get("description")
         template["queHint"] = "" if description is None else str(description)
+    if str(field.get("type") or "") == FieldType.subtable.value:
+        return _materialize_preserved_subtable_question(field, template=template)
     if str(field.get("type") or "") == FieldType.relation.value:
         return _normalize_relation_question_for_save(template, field=field)
     return template
@@ -13412,6 +13536,7 @@ def _build_form_payload_from_fields(
     for row in form_rows:
         _apply_row_widths(row)
     payload = default_form_payload(title, form_rows)
+    _normalize_formula_defaults_for_save(payload.get("formQues"))
     payload["editVersionNo"] = int(current_schema.get("editVersionNo") or 1)
     payload["questionRelations"] = _normalize_question_relations_for_save(
         question_relations if question_relations is not None else (current_schema.get("questionRelations") or [])
@@ -13529,6 +13654,7 @@ def _build_form_payload_for_edit_fields(
 
     payload = _build_form_save_base_payload(current_schema, title)
     payload["formQues"] = form_rows
+    _normalize_formula_defaults_for_save(payload.get("formQues"))
     payload["questionRelations"] = normalized_relations
     payload["editVersionNo"] = int(current_schema.get("editVersionNo") or 1)
     return payload
@@ -14945,6 +15071,7 @@ def _build_form_payload_from_existing_schema(
 
     payload = _build_form_save_base_payload(current_schema, str(current_schema.get("formTitle") or "未命名应用"))
     payload["formQues"] = form_rows
+    _normalize_formula_defaults_for_save(payload.get("formQues"))
     payload["questionRelations"] = _normalize_question_relations_for_save(current_schema.get("questionRelations") or [])
     payload["editVersionNo"] = int(current_schema.get("editVersionNo") or 1)
     payload.setdefault("formTitle", current_schema.get("formTitle") or "未命名应用")

package/src/qingflow_mcp/cli/commands/builder.py

@@ -101,7 +101,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     app_release_lock.add_argument("--lock-owner-name", required=True)
     app_release_lock.set_defaults(handler=_handle_app_release_edit_lock_if_mine, format_hint="builder_summary")
 
-    app_get = app_subparsers.add_parser("get", help="读取应用配置")
+    app_get = app_subparsers.add_parser("get", help="读取应用配置（字段请使用: builder app get --app-key APP fields）")
     app_get.add_argument(
         "builder_app_get_section",
         nargs="?",

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -2550,6 +2550,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "field.autoTrigger": "field.auto_trigger",
             "field.customBtnTextStatus": "field.custom_button_text_enabled",
             "field.customBtnText": "field.custom_button_text",
+            "field.subfieldUpdates": "field.subfield_updates",
         },
         "allowed_values": {
             "field.type": [member.value for member in PublicFieldType],
@@ -2636,6 +2637,9 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "relation_mode=multiple maps to referenceConfig.optionalDataNum=0",
             "relation fields now require both display_field and visible_fields in MCP/CLI payloads",
             "if relation target metadata lookup is blocked by 40161/40002/40027, explicit display_field.name and visible_fields[].name let builder degrade verification and still continue schema write",
+            "update_fields[].set.subfield_updates is the safe patch path for editing existing subtable child fields without rebuilding the entire subtable",
+            "subfield_updates only supports safe child overlays: name, required, description, and nested subfield_updates",
+            "set.subfields remains the full replace/rebuild path for a subtable and is higher risk when hidden relation/reference children exist",
             "department fields accept department_scope with mode=all or mode=custom; custom scope requires explicit departments[].dept_id and optional include_sub_departs",
             "q_linker_binding lets you declare request config, dynamic inputs, alias parsing, and target-field bindings in one step; builder writes remoteLookupConfig plus the existing backend relation-default and questionRelations structures",
             "code_block_binding lets you declare inputs, code, alias parsing, and target-field bindings in one step; builder writes codeBlockConfig plus the existing backend relation-default and questionRelations structures",
@@ -2683,6 +2687,26 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "update_fields": [],
             "remove_fields": [],
         },
+        "subfield_update_example": {
+            "profile": "default",
+            "app_key": "APP_REWARD",
+            "publish": True,
+            "add_fields": [],
+            "update_fields": [
+                {
+                    "selector": {"que_id": 441305044},
+                    "set": {
+                        "subfield_updates": [
+                            {
+                                "selector": {"que_id": 441305045},
+                                "set": {"name": "景品名"},
+                            }
+                        ]
+                    },
+                }
+            ],
+            "remove_fields": [],
+        },
         "department_scope_example": {
             "profile": "default",
             "app_key": "APP_LEAD",
@@ -3049,6 +3073,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "execution_notes": [
             "returns compact current field configuration for one app",
             "use this before app_schema_apply when you need exact field definitions",
+            "subtable fields include nested subfields using the same compact field shape",
         ],
         "minimal_example": {
             "profile": "default",