@josephyan/qingflow-app-builder-mcp 0.2.0-beta.2 → 0.2.0-beta.21

package/skills/qingflow-app-builder/references/update-schema.md

@@ -0,0 +1,90 @@
+# Update Schema
+
+Use this when the app already exists and the task is only about fields.
+
+## Minimal sequence
+
+1. `app_resolve`
+2. `app_read_fields`
+3. `app_schema_plan`
+4. `app_schema_apply`
+
+## Example
+
+Read current fields first:
+
+```json
+{
+  "tool_name": "app_read_fields",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123"
+  }
+}
+```
+
+Plan the patch:
+
+```json
+{
+  "tool_name": "app_schema_plan",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "add_fields": [
+      {"name": "跟进日期", "type": "date"}
+    ],
+    "update_fields": [
+      {"selector": {"name": "金额"}, "set": {"name": "订单金额", "required": true}}
+    ],
+    "remove_fields": [
+      {"name": "旧字段"}
+    ]
+  }
+}
+```
+
+Apply the patch:
+
+```json
+{
+  "tool_name": "app_schema_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "publish": true,
+    "add_fields": [
+      {"name": "跟进日期", "type": "date"}
+    ],
+    "update_fields": [
+      {"selector": {"name": "金额"}, "set": {"name": "订单金额", "required": true}}
+    ],
+    "remove_fields": [
+      {"name": "旧字段"}
+    ]
+  }
+}
+```
+
+## Common failures
+
+### `FIELD_NOT_FOUND`
+
+The selector did not match current schema. Re-read with `app_read_fields` and use `name`, `field_id`, or `que_id`.
+
+### `DUPLICATE_FIELD`
+
+The field already exists with a different shape. Switch from `add_fields` to `update_fields`.
+
+### `SCHEMA_APPLY_FAILED`
+
+Treat it as uncertain write state. Read back with `app_read_fields` before retrying.
+
+## Notes
+
+- `title` and `label` are accepted aliases for `name`
+- `textarea -> long_text`
+- `currency -> amount`
+- `mobile -> phone`
+- `select/radio -> single_select`
+- `checkbox -> multi_select`

package/skills/qingflow-app-builder/references/update-views.md

@@ -0,0 +1,184 @@
+# Update Views
+
+Use this when the task is only about table, card, board, or gantt views.
+
+## Minimal sequence
+
+1. `builder_tool_contract(tool_name="app_views_plan")`
+2. `app_read_fields`
+3. `app_read_views_summary`
+4. `app_views_plan`
+5. `app_views_apply`
+6. `app_read_views_summary` again whenever apply returns `failed` or `partial_success`
+
+If you are unsure about keys or view types, call `builder_tool_contract(tool_name="app_views_apply")` before guessing.
+
+Important verification rule:
+
+- `app_views_apply` can create a view object before every filter is fully verified in readback
+- Do not report “筛选已成功应用” unless the apply result also shows `verification.views_verified=true`
+- If apply returns `partial_success`, inspect `verification.by_view` and `details.filter_mismatches` before claiming the filters are active
+
+## Example
+
+Canonical rules before any example:
+
+- Always use `columns`
+- Do not emit `column_names`
+- Treat `fields` only as a legacy alias the MCP may normalize, not as the preferred shape
+- Use `filters` with canonical keys `field_name`, `operator`, `value`/`values`
+- For gantt, use `start_field`, `end_field`, and optionally `title_field`
+- If `app_read_views_summary` shows duplicate view names, include `view_key` in `upsert_views[]` and update that exact target
+
+Plan a default table view:
+
+```json
+{
+  "tool_name": "app_views_plan",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "upsert_views": [
+      {
+        "name": "全部订单",
+        "view_key": "VIEW_KEY_IF_DUPLICATE_NAMES_EXIST",
+        "type": "table",
+        "columns": ["订单编号", "客户名称", "订单金额", "状态"]
+      }
+    ],
+    "remove_views": []
+  }
+}
+```
+
+Apply it:
+
+```json
+{
+  "tool_name": "app_views_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "publish": true,
+    "upsert_views": [
+      {
+        "name": "全部订单",
+        "type": "table",
+        "columns": ["订单编号", "客户名称", "订单金额", "状态"]
+      }
+    ],
+    "remove_views": []
+  }
+}
+```
+
+After `app_views_plan` succeeds, prefer reusing its `suggested_next_call.arguments` directly. Do not rewrite aliases back into non-canonical keys such as `column_names`.
+
+Board example:
+
+```json
+{
+  "tool_name": "app_views_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "upsert_views": [
+      {
+        "name": "按状态看板",
+        "type": "board",
+        "group_by": "状态",
+        "columns": ["订单编号", "客户名称", "订单金额"]
+      }
+    ],
+    "remove_views": []
+  }
+}
+```
+
+Gantt example with filters:
+
+```json
+{
+  "tool_name": "app_views_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "upsert_views": [
+      {
+        "name": "项目甘特图",
+        "type": "gantt",
+        "columns": ["项目名称", "开始日期", "结束日期", "状态"],
+        "start_field": "开始日期",
+        "end_field": "结束日期",
+        "title_field": "项目名称",
+        "filters": [
+          {
+            "field_name": "状态",
+            "operator": "eq",
+            "value": "进行中"
+          }
+        ]
+      }
+    ],
+    "remove_views": []
+  }
+}
+```
+
+## Common failures
+
+### `UNKNOWN_VIEW_FIELD`
+
+At least one `columns` or `group_by` field name does not exist.
+
+### `INVALID_VIEW_TYPE`
+
+Public view types are only `table`, `card`, `board`, `gantt`.
+
+Map old or intuitive labels before calling the tool:
+
+- `tableView` -> `table`
+- `cardView` -> `card`
+- `kanban` -> `board`
+
+### `INVALID_GANTT_CONFIG`
+
+Gantt views require at least:
+
+- `start_field`
+- `end_field`
+
+Also make sure these field names already exist on the app.
+
+### `VIEW_APPLY_FAILED`
+
+The backend rejected the normalized view payload. Re-read fields and inspect `request_id` before retrying.
+
+Do not repeat `app_views_apply` with guessed keys. First:
+
+1. check `suggested_next_call`
+2. reuse `canonical_arguments` if present
+3. call `app_read_views_summary` to see whether any requested views landed anyway
+4. if needed, call `builder_tool_contract`
+5. retry only the minimal failed view patch
+
+### `VIEW_FILTER_READBACK_MISMATCH`
+
+The view object was created or updated, but the readback config did not keep the intended filter values.
+
+Treat this as:
+
+- the view exists
+- the filter is **not yet verified**
+
+Do not tell the user the filter is active until the readback verification matches the intended filter.
+
+## Notes
+
+- `fields` is accepted as an alias for `columns`, but skill examples should still use `columns`
+- `column_names` should not appear in skill examples
+- `app_read_views_summary` should be treated as canonical readback and now returns `columns`
+- If `app_views_apply` returns `AMBIGUOUS_VIEW`, stop and re-run `app_read_views_summary`; then retry with the exact `view_key`
+- `filters` are ANDed together as one flat condition group
+- `app_views_apply` publishes by default
+- For select-style filters, success means the backend preserved the option value in readback, not just that the view name now exists

package/src/qingflow_mcp/__init__.py

@@ -2,4 +2,4 @@ from __future__ import annotations
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.0b2"
+__version__ = "0.2.0b21"

package/src/qingflow_mcp/builder_facade/models.py

@@ -43,11 +43,30 @@ FIELD_TYPE_ALIASES: dict[str, PublicFieldType] = {
     "departments": PublicFieldType.department,
 }
 
+FIELD_TYPE_ID_ALIASES: dict[int, PublicFieldType] = {
+    2: PublicFieldType.text,
+    3: PublicFieldType.long_text,
+    4: PublicFieldType.date,
+    5: PublicFieldType.member,
+    6: PublicFieldType.email,
+    7: PublicFieldType.phone,
+    8: PublicFieldType.number,
+    10: PublicFieldType.boolean,
+    11: PublicFieldType.single_select,
+    12: PublicFieldType.multi_select,
+    13: PublicFieldType.attachment,
+    18: PublicFieldType.subtable,
+    21: PublicFieldType.address,
+    22: PublicFieldType.department,
+    25: PublicFieldType.relation,
+}
+
 
 class PublicViewType(str, Enum):
     table = "table"
     card = "card"
     board = "board"
+    gantt = "gantt"
 
 
 class LayoutApplyMode(str, Enum):
@@ -69,6 +88,7 @@ class FlowPreset(str, Enum):
 class ViewsPreset(str, Enum):
     default_table = "default_table"
     status_board = "status_board"
+    default_gantt = "default_gantt"
 
 
 class PublicFlowNodeType(str, Enum):
@@ -82,6 +102,143 @@ class PublicFlowNodeType(str, Enum):
     end = "end"
 
 
+class FlowConditionOperator(str, Enum):
+    eq = "eq"
+    neq = "neq"
+    in_ = "in"
+    contains = "contains"
+    gte = "gte"
+    lte = "lte"
+    is_empty = "is_empty"
+    not_empty = "not_empty"
+
+
+class ViewFilterOperator(str, Enum):
+    eq = "eq"
+    neq = "neq"
+    in_ = "in"
+    contains = "contains"
+    gte = "gte"
+    lte = "lte"
+    is_empty = "is_empty"
+    not_empty = "not_empty"
+
+
+class FlowAssigneePatch(StrictModel):
+    role_ids: list[int] = Field(default_factory=list)
+    role_names: list[str] = Field(default_factory=list)
+    member_uids: list[int] = Field(default_factory=list)
+    member_emails: list[str] = Field(default_factory=list)
+    member_names: list[str] = Field(default_factory=list)
+    include_sub_departs: bool | None = None
+
+
+class FlowNodePermissionsPatch(StrictModel):
+    editable_fields: list[str] = Field(default_factory=list)
+
+
+class FlowConditionRulePatch(StrictModel):
+    field_name: str = Field(validation_alias=AliasChoices("field_name", "fieldName", "field", "name"))
+    operator: FlowConditionOperator = Field(validation_alias=AliasChoices("operator", "op"))
+    values: list[Any] = Field(default_factory=list)
+
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_aliases(cls, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+        payload = dict(value)
+        if "value" in payload and "values" not in payload:
+            payload["values"] = [payload.pop("value")]
+        raw_operator = payload.get("operator", payload.get("op"))
+        if isinstance(raw_operator, str):
+            normalized = raw_operator.strip().lower()
+            operator_aliases = {
+                "equals": FlowConditionOperator.eq.value,
+                "equal": FlowConditionOperator.eq.value,
+                "=": FlowConditionOperator.eq.value,
+                "not_equals": FlowConditionOperator.neq.value,
+                "not_equal": FlowConditionOperator.neq.value,
+                "!=": FlowConditionOperator.neq.value,
+                ">=": FlowConditionOperator.gte.value,
+                "<=": FlowConditionOperator.lte.value,
+                "any_of": FlowConditionOperator.in_.value,
+                "one_of": FlowConditionOperator.in_.value,
+                "between_any": FlowConditionOperator.in_.value,
+                "empty": FlowConditionOperator.is_empty.value,
+                "is blank": FlowConditionOperator.is_empty.value,
+                "blank": FlowConditionOperator.is_empty.value,
+                "not_empty": FlowConditionOperator.not_empty.value,
+                "not blank": FlowConditionOperator.not_empty.value,
+            }
+            if normalized in operator_aliases:
+                payload["operator"] = operator_aliases[normalized]
+            elif "operator" not in payload:
+                payload["operator"] = normalized
+        payload.pop("op", None)
+        return payload
+
+    @model_validator(mode="after")
+    def validate_shape(self) -> "FlowConditionRulePatch":
+        if self.operator in {FlowConditionOperator.is_empty, FlowConditionOperator.not_empty}:
+            self.values = []
+            return self
+        if not self.values:
+            raise ValueError("condition rule requires values")
+        return self
+
+
+class ViewFilterRulePatch(StrictModel):
+    field_name: str = Field(validation_alias=AliasChoices("field_name", "fieldName", "field", "name"))
+    operator: ViewFilterOperator = Field(validation_alias=AliasChoices("operator", "op"))
+    values: list[Any] = Field(default_factory=list)
+
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_aliases(cls, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+        payload = dict(value)
+        if "value" in payload and "values" not in payload:
+            payload["values"] = [payload.pop("value")]
+        raw_operator = payload.get("operator", payload.get("op"))
+        if isinstance(raw_operator, str):
+            normalized = raw_operator.strip().lower()
+            operator_aliases = {
+                "equals": ViewFilterOperator.eq.value,
+                "equal": ViewFilterOperator.eq.value,
+                "=": ViewFilterOperator.eq.value,
+                "not_equals": ViewFilterOperator.neq.value,
+                "not_equal": ViewFilterOperator.neq.value,
+                "!=": ViewFilterOperator.neq.value,
+                ">=": ViewFilterOperator.gte.value,
+                "<=": ViewFilterOperator.lte.value,
+                "any_of": ViewFilterOperator.in_.value,
+                "one_of": ViewFilterOperator.in_.value,
+                "between_any": ViewFilterOperator.in_.value,
+                "empty": ViewFilterOperator.is_empty.value,
+                "is blank": ViewFilterOperator.is_empty.value,
+                "blank": ViewFilterOperator.is_empty.value,
+                "not_empty": ViewFilterOperator.not_empty.value,
+                "not blank": ViewFilterOperator.not_empty.value,
+            }
+            if normalized in operator_aliases:
+                payload["operator"] = operator_aliases[normalized]
+            elif "operator" not in payload:
+                payload["operator"] = normalized
+        payload.pop("op", None)
+        return payload
+
+    @model_validator(mode="after")
+    def validate_shape(self) -> "ViewFilterRulePatch":
+        if self.operator in {ViewFilterOperator.is_empty, ViewFilterOperator.not_empty}:
+            self.values = []
+            return self
+        if not self.values:
+            raise ValueError("view filter rule requires values")
+        return self
+
+
 class FieldSelector(StrictModel):
     field_id: str | None = None
     que_id: int | None = None
@@ -161,15 +318,65 @@ class FieldRemovePatch(StrictModel):
         return self
 
 
+def _coerce_layout_columns(value: Any) -> int | None:
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value if value > 0 else None
+    if isinstance(value, str):
+        stripped = value.strip()
+        if stripped.isdigit():
+            parsed = int(stripped)
+            return parsed if parsed > 0 else None
+    return None
+
+
+def _normalize_layout_rows(value: Any, *, columns: int | None = None) -> Any:
+    if not isinstance(value, list):
+        return value
+    if value and all(isinstance(item, list) for item in value):
+        return value
+    if not value:
+        return []
+    width = columns if columns and columns > 0 else None
+    if width is None:
+        return [list(value)]
+    return [list(value[index : index + width]) for index in range(0, len(value), width) if value[index : index + width]]
+
+
 class LayoutSectionPatch(StrictModel):
     section_id: str | None = Field(default=None, validation_alias=AliasChoices("section_id", "sectionId"))
     title: str
-    rows: list[list[str]] = Field(default_factory=list)
+    rows: list[list[Any]] = Field(default_factory=list)
+
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_aliases(cls, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+        payload = dict(value)
+        if "name" in payload and "title" not in payload:
+            payload["title"] = payload.pop("name")
+        shorthand: Any | None = None
+        if "rows" not in payload:
+            if "fields" in payload:
+                shorthand = payload.pop("fields")
+            elif "field_ids" in payload:
+                shorthand = payload.pop("field_ids")
+            if shorthand is not None:
+                payload["rows"] = _normalize_layout_rows(
+                    shorthand,
+                    columns=_coerce_layout_columns(payload.pop("columns", None)),
+                )
+        return payload
 
     @model_validator(mode="after")
     def validate_rows(self) -> "LayoutSectionPatch":
         if not self.rows:
             raise ValueError("section rows must be a non-empty list")
+        for row in self.rows:
+            if not isinstance(row, list) or not row:
+                raise ValueError("section rows must be a non-empty list")
         if not self.section_id:
             self.section_id = _slugify_title(self.title)
         return self
@@ -179,8 +386,54 @@ class FlowNodePatch(StrictModel):
     id: str
     type: PublicFlowNodeType
     name: str
+    assignees: FlowAssigneePatch = Field(default_factory=FlowAssigneePatch)
+    permissions: FlowNodePermissionsPatch = Field(default_factory=FlowNodePermissionsPatch)
+    conditions: list[FlowConditionRulePatch] = Field(default_factory=list)
+    condition_groups: list[list[FlowConditionRulePatch]] = Field(default_factory=list)
     config: dict[str, Any] = Field(default_factory=dict)
 
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_aliases(cls, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+        payload = dict(value)
+        assignees = dict(payload.get("assignees") or {})
+        permissions = dict(payload.get("permissions") or {})
+
+        for key in ("role_ids", "role_names", "member_uids", "member_emails", "member_names", "include_sub_departs"):
+            if key in payload and key not in assignees:
+                assignees[key] = payload.pop(key)
+        for key in ("editable_fields",):
+            if key in payload and key not in permissions:
+                permissions[key] = payload.pop(key)
+        if "filters" in payload and "conditions" not in payload:
+            payload["conditions"] = payload.pop("filters")
+        if "rules" in payload and "conditions" not in payload:
+            payload["conditions"] = payload.pop("rules")
+        if "conditionRules" in payload and "condition_groups" not in payload:
+            payload["condition_groups"] = payload.pop("conditionRules")
+        if "conditionGroups" in payload and "condition_groups" not in payload:
+            payload["condition_groups"] = payload.pop("conditionGroups")
+        if "owners" in payload and "member_names" not in assignees:
+            assignees["member_names"] = payload.pop("owners")
+        if "approvers" in payload and "role_names" not in assignees:
+            assignees["role_names"] = payload.pop("approvers")
+        if assignees:
+            payload["assignees"] = assignees
+        if permissions:
+            payload["permissions"] = permissions
+        return payload
+
+    @model_validator(mode="after")
+    def validate_branch_conditions(self) -> "FlowNodePatch":
+        if self.conditions:
+            self.condition_groups = [list(self.conditions), *self.condition_groups]
+            self.conditions = []
+        if self.type != PublicFlowNodeType.condition and self.condition_groups:
+            raise ValueError("condition_groups are only allowed on condition nodes")
+        return self
+
 
 class FlowTransitionPatch(StrictModel):
     source: str = Field(alias="from")
@@ -189,9 +442,14 @@ class FlowTransitionPatch(StrictModel):
 
 class ViewUpsertPatch(StrictModel):
     name: str
+    view_key: str | None = Field(default=None, validation_alias=AliasChoices("view_key", "viewKey"))
     type: PublicViewType
     columns: list[str] = Field(default_factory=list)
     group_by: str | None = None
+    filters: list[ViewFilterRulePatch] = Field(default_factory=list)
+    start_field: str | None = Field(default=None, validation_alias=AliasChoices("start_field", "startField"))
+    end_field: str | None = Field(default=None, validation_alias=AliasChoices("end_field", "endField"))
+    title_field: str | None = Field(default=None, validation_alias=AliasChoices("title_field", "titleField"))
 
     @model_validator(mode="before")
     @classmethod
@@ -201,6 +459,14 @@ class ViewUpsertPatch(StrictModel):
         payload = dict(value)
         if "fields" in payload and "columns" not in payload:
             payload["columns"] = payload.pop("fields")
+        if "column_names" in payload and "columns" not in payload:
+            payload["columns"] = payload.pop("column_names")
+        if "columnNames" in payload and "columns" not in payload:
+            payload["columns"] = payload.pop("columnNames")
+        if "filter_rules" in payload and "filters" not in payload:
+            payload["filters"] = payload.pop("filter_rules")
+        if "filterRules" in payload and "filters" not in payload:
+            payload["filters"] = payload.pop("filterRules")
         raw_type = payload.get("type")
         if isinstance(raw_type, str):
             normalized = raw_type.strip().lower()
@@ -210,6 +476,8 @@ class ViewUpsertPatch(StrictModel):
                 payload["type"] = "card"
             elif normalized == "kanban":
                 payload["type"] = "board"
+            elif normalized == "ganttview":
+                payload["type"] = "gantt"
         return payload
 
     @model_validator(mode="after")
@@ -218,6 +486,8 @@ class ViewUpsertPatch(StrictModel):
             raise ValueError("table/card views require columns")
         if self.type == PublicViewType.board and not self.group_by:
             raise ValueError("board view requires group_by")
+        if self.type == PublicViewType.gantt and not (self.start_field and self.end_field):
+            raise ValueError("gantt view requires start_field and end_field")
         return self
 
 
@@ -303,6 +573,22 @@ class FlowPlanRequest(StrictModel):
         payload = dict(value)
         if str(payload.get("mode") or "").strip().lower() == "overwrite":
             payload["mode"] = "replace"
+        raw_preset = payload.get("preset")
+        if raw_preset is None and isinstance(payload.get("base_preset"), str):
+            raw_preset = payload["base_preset"]
+            payload["preset"] = raw_preset
+        if isinstance(raw_preset, str):
+            normalized_preset = raw_preset.strip().lower()
+            preset_aliases = {
+                "default_approval": FlowPreset.basic_approval.value,
+                "approval": FlowPreset.basic_approval.value,
+                "basic approval": FlowPreset.basic_approval.value,
+                "default_fill_then_approve": FlowPreset.basic_fill_then_approve.value,
+                "default-fill-then-approve": FlowPreset.basic_fill_then_approve.value,
+                "fill_then_approve": FlowPreset.basic_fill_then_approve.value,
+            }
+            if normalized_preset in preset_aliases:
+                payload["preset"] = preset_aliases[normalized_preset]
         return payload
 
 
@@ -332,7 +618,14 @@ def _normalize_field_payload(value: Any) -> Any:
     if not isinstance(value, dict):
         return value
     payload = dict(value)
+    if "fields" in payload and "subfields" not in payload:
+        payload["subfields"] = payload.pop("fields")
     raw_type = payload.get("type")
+    if isinstance(raw_type, int):
+        normalized_from_id = FIELD_TYPE_ID_ALIASES.get(raw_type)
+        if normalized_from_id is not None:
+            payload["type"] = normalized_from_id.value
+            return payload
     if isinstance(raw_type, str):
         normalized = FIELD_TYPE_ALIASES.get(raw_type.strip().lower())
         if normalized is not None: