@josephyan/qingflow-app-builder-mcp 0.2.0-beta.14 → 0.2.0-beta.16

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.14
+npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.16
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.14 qingflow-app-builder-mcp
+npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.16 qingflow-app-builder-mcp
 ```
 
 Environment:
@@ -20,7 +20,7 @@ Environment:
 
 This package bootstraps a local Python runtime on first install and then starts the `qingflow-app-builder-mcp` stdio MCP server.
 
-Bundled skill:
+Bundled skills:
 
 - `skills/qingflow-app-builder`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-builder-mcp",
-  "version": "0.2.0-beta.14",
+  "version": "0.2.0-beta.16",
   "description": "Builder MCP for Qingflow app/package/system design and staged solution workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

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

package/skills/qingflow-app-builder/SKILL.md

@@ -152,6 +152,12 @@ For additive work on existing systems:
   - `permissions.editable_fields`
 - Reuse `app_flow_plan` output directly when it succeeds. Do not rewrite it into internal keys such as `role_entries` or `editable_que_ids`.
 - Reuse `app_views_plan` output directly when it succeeds. Do not re-expand aliases such as `column_names`.
+- For layout work, keep the public section shape canonical:
+  - `title`
+  - `rows`
+  Do not invent top-level layout `columns`, and do not prefer `fields` or `field_ids` once `rows` is known.
+- Translate natural language like “一行四个字段 / 四列布局 / 每行放四个” into `rows` matrices, not guessed layout parameters.
+- If the same layout-shape `VALIDATION_ERROR` repeats twice, stop guessing and re-read `builder_tool_contract(app_layout_plan)` or the layout reference before trying again.
 - Do not guess role ids or member ids. Resolve them from the directory first.
 - `app_schema_apply` does not treat package attachment as success criteria; if package ownership matters, verify `tag_ids_after` and call `package_attach_app` explicitly.
 - `package_attach_app` is the source of truth for package ownership; do not assume app creation or publish implicitly attaches the app.
@@ -167,6 +173,8 @@ For additive work on existing systems:
 - If readback mismatches the UI, compare `request_route` and do not assume the builder hit the same `qf_version` as the browser
 - Treat post-write readback as the source of truth, not just write status codes
 - For views, a top-level `VIEW_APPLY_FAILED` does not prove all requested views failed. Read back the view list and verify which views actually landed.
+- For views, “view exists” is not the same as “filters are active”. If `app_views_apply` returns `partial_success`, `views_verified=false`, or `details.filter_mismatches`, report the view as created but the filters as unverified until readback confirms them.
+- If multiple views share the same name, do not guess which one to update. Read `view_key` from `app_read_views_summary` and pass it explicitly in `upsert_views[]`.
 - In final user-facing summaries, distinguish clearly between:
   - contract is visible / canonical shape is known
   - plan succeeded

package/skills/qingflow-app-builder/references/gotchas.md

@@ -49,10 +49,14 @@
 - Do not repeat create steps after `app_key` already exists
 - For backend rejects, keep the retry narrow: retry only the failed tool, not the whole chain
 - For `VALIDATION_ERROR`, do not keep guessing. Reuse `suggested_next_call`, `canonical_arguments`, `allowed_keys`, and `allowed_values` first.
+- For layout `VALIDATION_ERROR`, also inspect `section_allowed_keys`, `section_aliases`, and `minimal_section_example`. If the same layout-shape error repeats twice, stop free-form retries and re-read `builder_tool_contract(app_layout_plan)`.
 - For flow work, do not replay internal keys from old logs or plan outputs. Public builder calls should stay on:
   - `assignees.role_ids` / `assignees.member_uids` / `assignees.member_emails`
   - `permissions.editable_fields`
 - For view work, treat `columns` as the only canonical public key. `app_read_views_summary` and `app_views_plan/apply` should all be read and written in that shape.
+- For layout work, treat `title + rows` as the only canonical public section shape. `fields`, `field_ids`, and `columns` may appear in legacy/internal shapes, but they are not the preferred public write shape.
+- A created view is not enough to claim a filter succeeded. When `app_views_apply` returns `partial_success`, `views_verified=false`, or `details.filter_mismatches`, treat the view as present but the filter as unverified.
+- If duplicate view names exist, do not retry by name. Read the exact `view_key` and target that one.
 - If a view or flow write fails, report the smallest next action:
   - wrong key -> switch to canonical key
   - unsupported preset -> switch to allowed canonical preset

package/skills/qingflow-app-builder/references/tool-selection.md

@@ -73,7 +73,7 @@ These execute normalized patches and publish by default unless `publish=false`.
 - Update fields on an existing app:
   `app_resolve -> app_read_fields -> app_schema_plan -> app_schema_apply`
 - Tidy layout:
-  `app_read_layout_summary -> app_layout_plan -> app_layout_apply`
+  `app_read_fields -> app_read_layout_summary -> builder_tool_contract (if shape is unclear) -> app_layout_plan -> app_layout_apply`
 - Add workflow:
   `builder_tool_contract -> app_read_fields -> app_read_flow_summary -> role_search/member_search -> app_flow_plan -> app_flow_apply -> app_read_flow_summary`
 - Add views:
@@ -88,6 +88,7 @@ These execute normalized patches and publish by default unless `publish=false`.
 - Do not compress multiple business objects into one app with several text fields
 - Do not skip summary reads before flow or view work
 - Do not emit `column_names`; always use `columns`
+- Do not model layout shape with `fields`, `field_ids`, or top-level `columns`; custom layout sections should be `title + rows`
 - Do not reuse internal flow keys such as `role_entries` or `editable_que_ids` in public builder calls
 - Do not pass natural-language preset guesses such as `default_approval`; map them to canonical preset values first
 - Do not omit assignees on approval/fill/copy nodes

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

@@ -6,12 +6,13 @@ Use this when fields already exist and the task is only about form grouping or o
 
 1. `app_read_fields`
 2. `app_read_layout_summary`
-3. `app_layout_plan`
-4. `app_layout_apply`
+3. `builder_tool_contract` when the section shape is not already obvious
+4. `app_layout_plan`
+5. `app_layout_apply`
 
 ## Example
 
-Plan a balanced merge layout:
+Plan a custom layout with the canonical public section shape:
 
 ```json
 {
@@ -74,8 +75,17 @@ Only happens in `mode=replace`. Switch to `mode=merge` unless you intend to plac
 
 Re-read with `app_read_layout_summary`. Check `current_field_names`, `request_id`, and `suggested_next_call`.
 
+### `VALIDATION_ERROR`
+
+Do not keep guessing section keys. Reuse `suggested_next_call`, `canonical_arguments`, `section_allowed_keys`, and `minimal_section_example`.
+
+If the same shape error repeats twice, stop free-form retries and re-read `builder_tool_contract(app_layout_plan)`.
+
 ## Notes
 
 - `section_id` is optional; it is generated from the section title
 - `merge` is safer than `replace`
 - Unmentioned fields stay in place or get auto-added to `未分组字段`
+- Public builder layout sections use `title + rows`
+- Do not treat “一行四个字段 / 四列布局 / 每行放四个” as a top-level `columns` parameter; translate it into a `rows` matrix
+- Do not prefer `fields` or `field_ids` once `rows` is known, even though MCP may normalize those shorthands for recovery

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

@@ -13,6 +13,12 @@ Use this when the task is only about table, card, board, or gantt views.
 
 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:
@@ -22,6 +28,7 @@ Canonical rules before any example:
 - 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:
 
@@ -34,6 +41,7 @@ Plan a default table view:
     "upsert_views": [
       {
         "name": "全部订单",
+        "view_key": "VIEW_KEY_IF_DUPLICATE_NAMES_EXIST",
         "type": "table",
         "columns": ["订单编号", "客户名称", "订单金额", "状态"]
       }
@@ -154,10 +162,23 @@ Do not repeat `app_views_apply` with guessed keys. First:
 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.0b14"
+__version__ = "0.2.0b16"

package/src/qingflow_mcp/builder_facade/models.py

@@ -318,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
@@ -392,6 +442,7 @@ 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