@josephyan/qingflow-app-user-mcp 1.1.26 → 1.1.28

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-user-mcp@1.1.26
+npm install @josephyan/qingflow-app-user-mcp@1.1.28
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-user-mcp@1.1.26 qingflow-app-user-mcp
+npx -y -p @josephyan/qingflow-app-user-mcp@1.1.28 qingflow-app-user-mcp
 ```
 
 Environment:
@@ -30,12 +30,10 @@ Bundled skills:
 - `skills/qingflow-task-ops`
 - `skills/qingflow-record-analysis`
 - `skills/qingflow-mcp-setup`
-- `skills/qingflow-app-builder`
-- `skills/qingflow-app-builder-code-integrations`
-- `skills/qingflow-workflow-builder`
 
 Note:
 
 - The skill files are included in the npm package.
-- On install, the package copies them to `$CODEX_HOME/skills` (or `~/.codex/skills` if `CODEX_HOME` is unset).
+- On install, the package installs bundled skills into `$CODEX_HOME/skills` (or `~/.codex/skills` if `CODEX_HOME` is unset) by symlink and refreshes them on package updates.
+- You can also run `qingflow-app-user-mcp skills list` or `qingflow-app-user-mcp skills install --agent codex|claude-code|cursor|generic --scope user|project [--copy] [--force]`.
 - If a stdio MCP client reports `Transport closed`, delete `.npm-python`, reinstall the package, and make sure CLI/user/builder packages are on the same version. The stdio entrypoints refuse runtime bootstrap so install logs never corrupt MCP stdout.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "1.1.26",
+  "version": "1.1.28",
   "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 = "1.1.26"
+version = "1.1.28"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

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

@@ -7,6 +7,8 @@ metadata:
 
 # Qingflow App User
 
+> **Skill 版本**：`qingflow-skills-2026.06.30.1`
+
 ## Overview
 
 This skill is a lightweight router for operational Qingflow work.
@@ -39,7 +41,7 @@ Route to exactly one of these specialized paths:
    Switch to [$qingflow-mcp-setup](../qingflow-mcp-setup/SKILL.md)
 
 8. App / view / workflow / chart / portal / package configuration
-   Switch to [$qingflow-app-builder](../qingflow-app-builder/SKILL.md)
+   This is builder work, not app-user work. Use the `qingflow-cli` skill or install/use the `qingflow-app-builder` package.
 
 ## Routing Rules
 
@@ -50,7 +52,7 @@ Route to exactly one of these specialized paths:
 - If the task is about deleting records directly, switch to `$qingflow-record-delete`
 - If the task is about import templates, import capability discovery, import-file verification, authorized local file repair, import execution, or import status, switch to `$qingflow-record-import`
 - If the task is about todo discovery, task context, approval actions, rollback or transfer, associated report review, or workflow log review, switch to `$qingflow-task-ops`
-- If the task is about package, app, field, layout, workflow, view, chart, portal, visibility, icon, or app base configuration, switch to `$qingflow-app-builder`
+- If the task is about package, app, field, layout, workflow, view, chart, portal, visibility, icon, or app base configuration, stop this app-user route and use the `qingflow-cli` skill or the `qingflow-app-builder` package
 - If the task involves member, department, or relation fields and the user only has natural names/titles, keep the same route; direct write now supports backend-native auto resolution and may return `needs_confirmation` with candidates instead of failing blind
 - If the task involves linked visibility, upstream/downstream field dependencies, reference-driven auto fill, or formula-driven defaulting, keep the same insert/update route and read field-level `linkage` from the schema before composing payloads
 - If the task is about subtable writes, still route to the matching insert/update skill, but shape the payload as parent subtable field -> row array; do not route users toward top-level leaf selectors
@@ -86,4 +88,4 @@ Route to exactly one of these specialized paths:
 - Record import: [$qingflow-record-import](../qingflow-record-import/SKILL.md)
 - Task workflow operations: [$qingflow-task-ops](../qingflow-task-ops/SKILL.md)
 - Dedicated analysis workflow: [$qingflow-record-analysis](../qingflow-record-analysis/SKILL.md)
-- Builder workflow: [$qingflow-app-builder](../qingflow-app-builder/SKILL.md)
+- Builder workflow: use the `qingflow-cli` skill or the `qingflow-app-builder` package

package/skills/qingflow-app-user/references/public-surface-sync.md

@@ -33,20 +33,22 @@ It is not a user-facing product spec. It exists to prevent skill drift.
 
 ### Builder
 
+- Builder work belongs to the `qingflow-cli` skill or the `qingflow-app-builder` package; this app-user package only records the boundary to prevent routing drift.
 - Official package entry: `package_get`, `package_apply`
 - Official builder writes:
   - `app_schema_apply`
   - `app_layout_apply`
   - `app_flow_apply`
   - `app_views_apply`
-  - `app_custom_buttons_apply`
   - `app_associated_resources_apply`
   - `app_charts_apply`
   - `portal_apply`
   - `app_publish_verify`
+- Complete-system main path: package -> schema apps with `form.sections` and `target_app_ref` -> views with `action_buttons` -> portal with inline `sections[].chart`
+- Single-app main path: resolve/get -> schema with `form.sections` -> views with `action_buttons`; do not default to portal
 - `portal_apply` edit mode may omit `sections` for base-info-only updates
 - `app_charts_apply.visibility` is a public capability and should be treated as a base-only visibility update
-- Existing object parameter replacement should use `patch_views`, `patch_buttons`, `patch_resources`, and `patch_charts`; `upsert_*` is for creation or full target config
+- Existing object parameter replacement should use `patch_views`, `patch_resources`, and `patch_charts`; `upsert_*` is for creation or full target config
 - `app_get.editability` uses:
   - `can_edit_app_base`
   - `can_edit_form`

package/src/qingflow_mcp/builder_facade/models.py

@@ -72,6 +72,9 @@ class PublicExternalVisibilityMode(str, Enum):
 
 FIELD_TYPE_ALIASES: dict[str, PublicFieldType] = {
     "textarea": PublicFieldType.long_text,
+    "multiline": PublicFieldType.long_text,
+    "multi_line": PublicFieldType.long_text,
+    "multiline_text": PublicFieldType.long_text,
     "amount": PublicFieldType.amount,
     "currency": PublicFieldType.amount,
     "mobile": PublicFieldType.phone,
@@ -1456,6 +1459,9 @@ class CustomButtonViewButtonBindingPatch(StrictModel):
         raw_limits = payload.get("button_limit", payload.get("buttonLimit", payload.get("visible_when", payload.get("visibleWhen"))))
         if isinstance(raw_limits, list) and raw_limits and all(isinstance(item, dict) for item in raw_limits):
             payload["button_limit"] = [raw_limits]
+        for alias in ("buttonLimit", "visible_when", "visibleWhen"):
+            if alias in payload and alias != "button_limit":
+                payload.pop(alias, None)
         return payload
 
 
@@ -1642,7 +1648,7 @@ class ViewButtonBindingPatch(StrictModel):
     being_main: bool = Field(default=False, validation_alias=AliasChoices("being_main", "beingMain"))
     button_limit: list[list[ViewFilterRulePatch]] = Field(
         default_factory=list,
-        validation_alias=AliasChoices("button_limit", "buttonLimit"),
+        validation_alias=AliasChoices("button_limit", "buttonLimit", "visible_when", "visibleWhen"),
     )
     button_formula: str | None = Field(default=None, validation_alias=AliasChoices("button_formula", "buttonFormula"))
     button_formula_type: int = Field(default=1, validation_alias=AliasChoices("button_formula_type", "buttonFormulaType"))
@@ -1671,9 +1677,12 @@ class ViewButtonBindingPatch(StrictModel):
                 payload["config_type"] = "DETAIL"
             elif normalized_config in {"inside", "list", "row", "row_action"}:
                 payload["config_type"] = "INSIDE"
-        raw_limits = payload.get("button_limit", payload.get("buttonLimit"))
+        raw_limits = payload.get("button_limit", payload.get("buttonLimit", payload.get("visible_when", payload.get("visibleWhen"))))
         if isinstance(raw_limits, list) and raw_limits and all(isinstance(item, dict) for item in raw_limits):
             payload["button_limit"] = [raw_limits]
+        for alias in ("buttonLimit", "visible_when", "visibleWhen"):
+            if alias in payload and alias != "button_limit":
+                payload.pop(alias, None)
         return payload
 
     @model_validator(mode="after")
@@ -1763,68 +1772,63 @@ class ChartFilterRulePatch(StrictModel):
         return self
 
 
-_CHART_METRIC_RE = re.compile(r"^\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\((.*)\)\s*$")
-
-
-def _normalize_chart_string_list(value: Any) -> list[str]:
-    if value is None:
-        return []
-    if isinstance(value, (list, tuple)):
-        return [str(item).strip() for item in value if item is not None and str(item).strip()]
-    raw = str(value).strip()
-    return [raw] if raw else []
+class ChartMetricPatch(StrictModel):
+    op: str = "count"
+    field_name: str | None = Field(default=None, validation_alias=AliasChoices("field", "field_name", "fieldName", "name"))
+    alias: str | None = None
 
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_metric(cls, value: Any) -> Any:
+        if isinstance(value, str):
+            raw = value.strip()
+            match = re.fullmatch(r"([A-Za-z_][A-Za-z0-9_]*)\s*\(\s*(.*?)\s*\)", raw)
+            if match:
+                op = match.group(1).strip().lower()
+                field = match.group(2).strip()
+                payload: dict[str, Any] = {"op": op}
+                if field and field != "*":
+                    payload["field_name"] = field
+                return payload
+            if raw:
+                return {"op": "sum", "field_name": raw}
+            return {"op": "count"}
+        if not isinstance(value, dict):
+            return value
+        payload = dict(value)
+        if "operation" in payload and "op" not in payload:
+            payload["op"] = payload.pop("operation")
+        if "agg" in payload and "op" not in payload:
+            payload["op"] = payload.pop("agg")
+        if "aggregate" in payload and "op" not in payload:
+            payload["op"] = payload.pop("aggregate")
+        if "aggregation" in payload and "op" not in payload:
+            payload["op"] = payload.pop("aggregation")
+        return payload
 
-def _parse_chart_metric_item(value: Any) -> tuple[list[str], str | None]:
-    if value is None:
-        return [], None
-    if isinstance(value, dict):
-        op = str(value.get("op") or value.get("agg") or value.get("aggregate") or value.get("aggregation") or "").strip().lower()
-        field = value.get("field", value.get("field_name", value.get("name", value.get("selector"))))
-        selectors = _normalize_chart_string_list(field)
-        return selectors, op or ("count" if not selectors else None)
-    raw = str(value).strip()
-    if not raw:
-        return [], None
-    matched = _CHART_METRIC_RE.match(raw)
-    if matched:
-        op = matched.group(1).strip().lower()
-        field = matched.group(2).strip()
-        if field in {"*", ""}:
-            return [], op
-        return [field], op
-    if raw.lower() in {"count", "count(*)"}:
-        return [], "count"
-    return [raw], None
-
-
-def _apply_semantic_chart_metric_aliases(payload: dict[str, Any]) -> None:
-    raw_metrics: list[Any] = []
-    if "metric" in payload:
-        raw_metrics.append(payload.pop("metric"))
-    if "metrics" in payload:
-        metrics = payload.pop("metrics")
-        raw_metrics.extend(metrics if isinstance(metrics, list) else [metrics])
-    if not raw_metrics:
-        return
-    selectors: list[str] = []
-    aggregates: list[str] = []
-    for metric in raw_metrics:
-        metric_selectors, aggregate = _parse_chart_metric_item(metric)
-        selectors.extend(metric_selectors)
-        if aggregate:
-            aggregates.append(aggregate)
-    if selectors and "indicator_field_ids" not in payload:
-        payload["indicator_field_ids"] = selectors
-    if aggregates:
-        normalized_aggregate = aggregates[0]
-        config = payload.get("config")
-        if not isinstance(config, dict):
-            config = {}
-        else:
-            config = dict(config)
-        config.setdefault("aggregate", normalized_aggregate)
-        payload["config"] = config
+    @model_validator(mode="after")
+    def validate_metric(self) -> "ChartMetricPatch":
+        normalized_op = str(self.op or "count").strip().lower()
+        op_aliases = {
+            "average": "avg",
+            "mean": "avg",
+            "total": "sum",
+            "cnt": "count",
+            "count_all": "count",
+        }
+        self.op = op_aliases.get(normalized_op, normalized_op)
+        if self.field_name is not None:
+            field_name = str(self.field_name).strip()
+            self.field_name = field_name or None
+        if self.alias is not None:
+            alias = str(self.alias).strip()
+            self.alias = alias or None
+        supported = {"count", "sum", "avg", "max", "min"}
+        if self.op not in supported:
+            raise ValueError(f"chart metric op must be one of {sorted(supported)}")
+        if self.op != "count" and not self.field_name:
+            raise ValueError(f"chart metric op '{self.op}' requires field")
+        return self
 
 
 class ChartUpsertPatch(StrictModel):
@@ -1834,6 +1838,17 @@ class ChartUpsertPatch(StrictModel):
     dimension_field_ids: list[str] = Field(default_factory=list)
     indicator_field_ids: list[str] = Field(default_factory=list)
     filters: list[ChartFilterRulePatch] = Field(default_factory=list)
+    group_by: list[str] = Field(default_factory=list)
+    rows: list[str] = Field(default_factory=list)
+    columns: list[str] = Field(default_factory=list)
+    metric: ChartMetricPatch | None = None
+    metrics: list[ChartMetricPatch] = Field(default_factory=list)
+    x_metric: ChartMetricPatch | None = None
+    y_metric: ChartMetricPatch | None = None
+    left_metric: ChartMetricPatch | None = None
+    right_metric: ChartMetricPatch | None = None
+    value_metric: ChartMetricPatch | None = None
+    target_metric: ChartMetricPatch | None = None
     question_config: list[dict[str, Any]] = Field(default_factory=list)
     user_config: list[dict[str, Any]] = Field(default_factory=list)
     config: dict[str, Any] = Field(default_factory=dict)
@@ -1851,19 +1866,74 @@ class ChartUpsertPatch(StrictModel):
             payload["chart_type"] = payload.pop("type")
         if "dimension_fields" in payload and "dimension_field_ids" not in payload:
             payload["dimension_field_ids"] = payload.pop("dimension_fields")
+        if "dimensions" in payload and "dimension_field_ids" not in payload and "group_by" not in payload:
+            payload["group_by"] = payload.pop("dimensions")
+        if "groupBy" in payload and "group_by" not in payload:
+            payload["group_by"] = payload.pop("groupBy")
+        if "where" in payload and "filters" not in payload:
+            payload["filters"] = payload.pop("where")
+        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")
         if "indicator_fields" in payload and "indicator_field_ids" not in payload:
             payload["indicator_field_ids"] = payload.pop("indicator_fields")
         if "metric_field_ids" in payload and "indicator_field_ids" not in payload:
             payload["indicator_field_ids"] = payload.pop("metric_field_ids")
-        if "group_by" in payload and "dimension_field_ids" not in payload:
-            payload["dimension_field_ids"] = _normalize_chart_string_list(payload.pop("group_by"))
-        if "groupBy" in payload and "dimension_field_ids" not in payload:
-            payload["dimension_field_ids"] = _normalize_chart_string_list(payload.pop("groupBy"))
-        if "where" in payload and "filters" not in payload:
-            payload["filters"] = payload.pop("where")
-        else:
-            payload.pop("where", None)
-        _apply_semantic_chart_metric_aliases(payload)
+        metric_slots: list[Any] = []
+        generic_metric_keys = ("metric", "metrics")
+        axis_metric_keys = (
+            "x_metric",
+            "xMetric",
+            "y_metric",
+            "yMetric",
+            "left_metric",
+            "leftMetric",
+            "right_metric",
+            "rightMetric",
+            "value_metric",
+            "valueMetric",
+            "target_metric",
+            "targetMetric",
+        )
+
+        def has_metric_value(key: str) -> bool:
+            entry = payload.get(key)
+            return entry is not None and entry != "" and entry != []
+
+        if any(has_metric_value(key) for key in generic_metric_keys) and any(has_metric_value(key) for key in axis_metric_keys):
+            raise ValueError(
+                "chart metric input is ambiguous: use either metric/metrics or axis-specific "
+                "x_metric/y_metric, left_metric/right_metric, value_metric/target_metric, not both"
+            )
+        if "metric" in payload and "metrics" not in payload:
+            payload["metrics"] = [payload["metric"]]
+        for key in ("x_metric", "xMetric", "left_metric", "leftMetric", "value_metric", "valueMetric"):
+            if key in payload:
+                slot_value = payload.get(key)
+                if slot_value is not None:
+                    metric_slots.append(slot_value)
+                canonical = {
+                    "xMetric": "x_metric",
+                    "leftMetric": "left_metric",
+                    "valueMetric": "value_metric",
+                }.get(key)
+                if canonical and canonical not in payload:
+                    payload[canonical] = payload.pop(key)
+        for key in ("y_metric", "yMetric", "right_metric", "rightMetric", "target_metric", "targetMetric"):
+            if key in payload:
+                slot_value = payload.get(key)
+                if slot_value is not None:
+                    metric_slots.append(slot_value)
+                canonical = {
+                    "yMetric": "y_metric",
+                    "rightMetric": "right_metric",
+                    "targetMetric": "target_metric",
+                }.get(key)
+                if canonical and canonical not in payload:
+                    payload[canonical] = payload.pop(key)
+        if metric_slots and "metrics" not in payload:
+            payload["metrics"] = metric_slots
         raw_type = payload.get("chart_type")
         if isinstance(raw_type, str):
             normalized = raw_type.strip().lower()
@@ -1890,8 +1960,31 @@ class ChartUpsertPatch(StrictModel):
             payload["dimension_field_ids"] = [str(item) for item in payload["dimension_field_ids"] if item is not None and str(item).strip()]
         if isinstance(payload.get("indicator_field_ids"), list):
             payload["indicator_field_ids"] = [str(item) for item in payload["indicator_field_ids"] if item is not None and str(item).strip()]
+        for key in ("group_by", "rows", "columns"):
+            if isinstance(payload.get(key), str):
+                payload[key] = [payload[key]]
+            if isinstance(payload.get(key), list):
+                payload[key] = [str(item) for item in payload[key] if item is not None and str(item).strip()]
         return payload
 
+    @model_validator(mode="after")
+    def apply_semantic_chart_fields(self) -> "ChartUpsertPatch":
+        if self.group_by and not self.dimension_field_ids:
+            self.dimension_field_ids = list(self.group_by)
+        if self.rows and not self.dimension_field_ids:
+            self.dimension_field_ids = list(self.rows)
+        semantic_metrics: list[ChartMetricPatch] = []
+        if self.metrics:
+            semantic_metrics.extend(self.metrics)
+        for metric in (self.x_metric, self.y_metric, self.left_metric, self.right_metric, self.value_metric, self.target_metric):
+            if metric is not None and metric not in semantic_metrics:
+                semantic_metrics.append(metric)
+        if semantic_metrics and not self.metrics:
+            self.metrics = semantic_metrics
+        if self.metrics and not self.metric:
+            self.metric = self.metrics[0]
+        return self
+
 
 class ChartPartialPatch(StrictModel):
     chart_id: str | None = None
@@ -2287,6 +2380,9 @@ class ChartGetResponse(StrictModel):
     chart_id: str
     base: dict[str, Any] = Field(default_factory=dict)
     visibility: dict[str, Any] = Field(default_factory=dict)
+    filters: list[list[dict[str, Any]]] = Field(default_factory=list)
+    group_by: list[str] = Field(default_factory=list)
+    metrics: list[dict[str, Any]] = Field(default_factory=list)
     config: dict[str, Any] = Field(default_factory=dict)