@josephyan/qingflow-app-user-mcp 0.2.0-beta.13 → 0.2.0-beta.15

package/README.md

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

package/package.json

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

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

@@ -81,6 +81,7 @@ Do not use builder-side tools here:
 
 - Prefer `record_query` as the default read entry
 - Treat `record_query(list)` as the default wide-table browse and export endpoint; pass explicit `select_columns`, do not expect raw answer arrays there, and let the tool auto-batch columns when the backend per-request field cap is hit
+- If the user is asking for `分析 / 洞察 / 分布 / 占比 / 平均 / 排名 / 趋势 / 所有 / 全部 / 全国 / 高价值`, treat the task as analysis-first and start with `record_query_plan`
 - Use `request_route` from tool responses to verify the active `base_url` and `qf_version` whenever route mismatches are plausible
 - Use `directory_search` for fuzzy internal lookup across both members and departments
 - Use `directory_list_all_internal_users` when the user explicitly wants a complete internal member list within the current workspace or within a specific department or role
@@ -90,6 +91,7 @@ Do not use builder-side tools here:
 - Use `task_list_grouped` when worksheet or group buckets matter
 - Use `task_urge` only when the user clearly wants a reminder sent for a pending task
 - Use `record_query_plan` before final statistics or when field selectors are ambiguous
+- If the target fields are still uncertain, use the fixed order `record_field_resolve -> record_query_plan -> record_query/record_aggregate`; do not bounce between read tools by trial and error
 - For precise record lookup, use `record_get` when `apply_id` is known
 - Use `record_field_resolve` when the user gives field titles and you are not fully sure about the exact schema; do not guess ambiguous fields silently
 - Treat field selectors as schema-first and platform-generic. Prefer exact field titles, then neutral aliases such as `创建时间`, `新增时间`, `负责人`, `部门`, `时间`, or `阶段` only when the tool resolves them clearly. Do not assume CRM shorthand like `销售`, `商机阶段`, `客户全称`, or similar domain shortcuts apply across arbitrary Qingflow apps
@@ -97,6 +99,13 @@ Do not use builder-side tools here:
 - For deletes, confirm the exact record scope and report the deleted ids
 - When validating business data volume, use `effective_count` over raw backend totals
 - For summary or aggregate conclusions, prefer `strict_full=true`
+- For distribution, ratio, or final-count analysis, prefer the fixed order:
+  1. `record_query_plan`
+  2. `record_query(query_mode="summary")`
+  3. `record_aggregate`
+- For analysis routes, prefer `auto_expand_pages=true` unless the user explicitly wants a quick exploratory sample
+- Do not use `record_query(list)` as the basis for final averages, ratios, rankings, trends, or “全部数据” claims; it is sample browsing only when capped
+- If `record_query_plan` returns `estimate.recommended_arguments` or `suggested_next_call`, reuse those arguments instead of guessing scan parameters manually
 - In `prod`, prefer read-first even more strictly and avoid deletes unless the record scope is explicit in the conversation
 - For attachments, first run `file_upload_local`, then pass the returned `attachment_value` into `record_create` or `record_update`; do not try to write local file paths directly into attachment fields
 - For relation fields, first query the target app and resolve the referenced record `apply_id`; do not assume titles, numbers, or business keys can be written directly into a relation field
@@ -126,6 +135,14 @@ When the user asks for demo data, seed, smoke data, or mock data:
 
 - low-level list totals from the backend may report `0` while rows are present; prefer `record_query(summary)` or `record_aggregate` for final conclusions
 - `record_query(summary)` and `record_aggregate` expose `completeness`; do not treat partial scans as final conclusions
+- `record_query(summary)` and `record_aggregate` now also expose `analysis_status`, `safe_for_final_conclusion`, and `analysis_counts`; if `status=partial_success` or `safe_for_final_conclusion=false`, do not present the result as final
+- If an analysis answer did not use `record_query_plan`, downgrade the wording to `初步观察`; do not call it `结论` or `洞察`
+- If `record_query(list)` reports `row_cap_hit`, `sample_only`, capped `returned_items`, or compact output, explicitly say it is a sample rather than full data
+- If summary/aggregate is full but list evidence is sample-only, report them separately as:
+  - `全量可信结论`
+  - `样本观察（不作为最终结论）`
+  - optional `待验证假设`
+- For aggregate or summary answers, report both `backend_total_count` and `scanned_count` when coverage matters
 - `record_write_plan` is static preflight, not a guarantee that submit will pass runtime linkage or visibility checks
 - `record_create` now returns integer `apply_id`; you can pass that id directly into `record_get`, `record_update`, or `record_delete`
 - `verify_write=true` means the tool read the record back and compared the written fields; if it returns `status=verification_failed` or `ok=false`, do not report the create or update as successful
@@ -149,6 +166,10 @@ When the user asks for demo data, seed, smoke data, or mock data:
 - Attachment write: upload first, write the returned URL object second, and prefer `verify_write=true`
 - Relation write: query the target app first, capture the referenced record `apply_id`, then write the relation field and verify the readback
 - Production discrepancy triage: compare the response `request_route` with the browser environment before assuming the data query is wrong
+- Final analysis reporting template:
+  - `全量可信结论`
+  - `样本观察`
+  - `待验证假设`
 
 ## Resources
 

package/skills/qingflow-app-user/references/data-gotchas.md

@@ -3,8 +3,16 @@
 ## Counts
 
 - Prefer `effective_count`
-- For `record_query(summary)` and `record_aggregate`, inspect `completeness` before concluding
+- For `record_query(summary)` and `record_aggregate`, inspect `completeness`, `analysis_status`, and `safe_for_final_conclusion` before concluding
+- If `status=partial_success`, treat the result as exploratory unless the user explicitly asked for a partial sample
+- `record_query(list)` is for browsing and sample inspection. If it reports `row_cap_hit`, `sample_only`, or capped `returned_items`, do not present it as full data
+- When coverage matters, surface:
+  - `backend_total_count`
+  - `scanned_count`
+  - `unscanned_count`
+- Reuse `suggested_next_call` or `estimate.recommended_arguments` instead of inventing bigger scan settings by hand
 - If the browser and MCP disagree, compare `request_route.base_url` and `request_route.qf_version` first
+- Do not mix a full aggregate total with sample-only list detail in one sentence like “基于全部数据分析”； split the answer into `全量结论` and `样本观察`
 
 ## Record titles
 
@@ -16,6 +24,7 @@
 - `record_write_plan` is static preflight only; linked visibility and runtime required rules can still reject writes
 - `record_write_plan` now exposes `write_format.support_level`; check `full / restricted / unsupported` before attempting non-trivial writes
 - Use `record_field_resolve` when field titles are uncertain instead of guessing ids
+- For analysis tasks, use the fixed preflight order `record_field_resolve -> record_query_plan -> summary/aggregate`; do not switch tools blindly after `FIELD_NOT_FOUND` or ambiguity
 - Prefer `strict_full=true` for final statistics or business conclusions
 - `record_create` and `record_update` can do post-write verification with `verify_write=true`; use that for complex, subtable, or production writes
 - `apply_id` is normalized to an integer; pass it directly into later record tools

package/skills/qingflow-app-user/references/record-patterns.md

@@ -15,6 +15,32 @@ Use `record_query_plan` first when:
 - filters are still in natural-language shape
 - the result may be used as a final conclusion
 - scan scope or completeness is unclear
+- the user asks for a distribution, ratio, ranking, top-N, or any grouped aggregate
+- the user asks for `分析 / 洞察 / 分布 / 占比 / 平均 / 排名 / 趋势 / 所有 / 全部 / 全国 / 高价值`
+
+## Final analysis pattern
+
+1. Run `record_query_plan`
+2. If the plan exposes `estimate.recommended_arguments` or `suggested_next_call`, prefer those arguments directly
+3. Run `record_query(query_mode="summary", strict_full=true, auto_expand_pages=true)` to confirm the total scope
+4. Run `record_aggregate(strict_full=true, auto_expand_pages=true)` for grouped results
+5. Run `record_query(query_mode="list")` only if you still need sample rows or examples
+6. Report `backend_total_count`, `scanned_count`, and whether the result is safe for a final conclusion
+7. If `status=partial_success` or `safe_for_final_conclusion=false`, stop at “partial result” instead of presenting a final business conclusion
+8. If list rows are sample-only, separate the answer into:
+   - `全量可信结论`
+   - `样本观察（不作为最终结论）`
+   - optional `待验证假设`
+
+## Analysis anti-pattern
+
+Do not do this:
+
+1. Run only `record_query(query_mode="list")`
+2. Get `200` rows back
+3. Report平均值、占比、地域分布 as if they were based on all records
+
+This is not acceptable because the list endpoint can be capped. Use `record_query_plan -> summary -> aggregate` first, then treat list rows as sample-only evidence.
 
 ## Create pattern
 

package/src/qingflow_mcp/__init__.py

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

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