@josephyan/qingflow-app-user-mcp 0.2.0-beta.19 → 0.2.0-beta.20

package/README.md

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

package/package.json

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

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

@@ -9,8 +9,8 @@ For final statistics, grouped distributions, or insight-style analysis, use [$qi
 - If `record_analyze.status!=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`
+  - `presentation.statement_scope`
 - Use narrower views, filters, or smaller analysis questions instead of inventing manual 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 `样本观察`

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

@@ -26,7 +26,7 @@ Use [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/
 2. Generate one or more field_id-based DSLs
 3. Run `record_analyze(strict_full=true)` for summary/distribution/trend/cross analysis
 4. Run `record_query(query_mode="list")` only if you still need sample rows or examples
-5. Report `backend_total_count`, `scanned_count`, and whether the result is safe for a final conclusion
+5. Report `scanned_count`, `presentation.statement_scope`, and whether the result is safe for a final conclusion
 6. If `status=error` or `safe_for_final_conclusion=false`, stop at “partial result” instead of presenting a final business conclusion
 7. If list rows are sample-only, separate the answer into:
    - `全量可信结论`

package/skills/qingflow-record-analysis/references/analysis-patterns.md

@@ -32,10 +32,10 @@ Use this skill when the user asks for:
    - sort by the count alias
 5. Run `record_analyze`
 6. Report:
-   - `backend_total_count`
    - `scanned_count`
    - `safe_for_final_conclusion`
    - `presentation.statement_scope`
+   - `completeness.local_filtering_applied` when it affects how the result should be framed
 7. If grouped rows are truncated, describe the answer as `主要分组` or `已返回分组中`, not `各部门` or `全部`
 
 ## penetration / conversion / share-of-total pattern

package/skills/qingflow-record-analysis/references/confidence-reporting.md

@@ -78,7 +78,6 @@ If the user asked for multiple conclusions but only some are complete:
 
 ### 全量可信结论
 
-- `backend_total_count=1134`
 - `scanned_count=1134`
 - `safe_for_final_conclusion=true`
 - 这里写最终业务结论

package/src/qingflow_mcp/__init__.py

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

package/src/qingflow_mcp/tools/record_tools.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import json
 import re
+import time
 from dataclasses import dataclass
 from datetime import UTC, datetime
 from typing import cast
@@ -459,7 +460,8 @@ class RecordTools(ToolBase):
     def _schema_role_hints(self, field: FormField) -> JSONObject:
         field_family = self._schema_field_family(field)
         time_candidate = field.que_type in DATE_QUE_TYPES
-        metric_candidate = bool(field.que_type == 8 and not field.system and not field.readonly)
+        identifier_like = self._schema_is_identifier_like(field, field_family=field_family)
+        metric_candidate = bool(field.que_type == 8 and not field.system and not field.readonly and not identifier_like)
         dimension_candidate = bool(
             field.que_type not in ATTACHMENT_QUE_TYPES | RELATION_QUE_TYPES | SUBTABLE_QUE_TYPES | VERIFY_UNSUPPORTED_WRITE_QUE_TYPES
             and not field.system
@@ -474,6 +476,8 @@ class RecordTools(ToolBase):
         }
 
     def _schema_field_family(self, field: FormField) -> str:
+        if self._schema_is_identifier_like(field):
+            return "text"
         que_type = field.que_type
         if que_type == 8:
             return "number"
@@ -493,9 +497,21 @@ class RecordTools(ToolBase):
             return "unknown"
         return "text"
 
+    def _schema_is_identifier_like(self, field: FormField, *, field_family: str | None = None) -> bool:
+        normalized_title = _normalize_field_lookup_key(field.que_title)
+        if field.que_id == 0:
+            return True
+        if any(
+            token in normalized_title for token in ("编号", "单号", "流水号", "编码", "序号", "uid", "id", "code")
+        ):
+            return True
+        return False
+
     def _schema_supported_metric_ops(self, field: FormField, *, field_family: str) -> list[str]:
         if field.que_type in ATTACHMENT_QUE_TYPES | RELATION_QUE_TYPES | SUBTABLE_QUE_TYPES:
             return []
+        if self._schema_is_identifier_like(field, field_family=field_family):
+            return ["distinct_count"]
         if field_family == "number":
             return ["sum", "avg", "min", "max", "distinct_count"]
         if field_family in {"date", "category", "member", "department", "text", "boolean", "unknown"}:
@@ -503,6 +519,8 @@ class RecordTools(ToolBase):
         return []
 
     def _schema_semantic_hint(self, field: FormField, *, field_family: str) -> str:
+        if self._schema_is_identifier_like(field, field_family=field_family):
+            return "unknown"
         if field_family != "number":
             return "unknown"
         normalized_title = _normalize_field_lookup_key(field.que_title)
@@ -908,6 +926,7 @@ class RecordTools(ToolBase):
         strict_full: bool,
         output_profile: str,
     ) -> JSONObject:
+        started_at = time.perf_counter()
         analysis_paging = _fixed_analysis_scan_policy()
         page_size = int(analysis_paging["page_size"])
         requested_pages = int(analysis_paging["requested_pages"])
@@ -922,7 +941,7 @@ class RecordTools(ToolBase):
         has_more = False
         dept_member_cache: dict[int, set[int]] = {}
         local_filtering = bool(filters) or bool(view_selection is not None and view_selection.conditions)
-        group_stats: dict[str, JSONObject] = {}
+        group_stats: dict[tuple[tuple[str, object], ...], JSONObject] = {}
         overall_metrics = self._initialize_metric_states(metrics)
         matched_rows = 0
         scan_control: JSONObject = {
@@ -974,8 +993,11 @@ class RecordTools(ToolBase):
                 if not self._matches_analyze_filters(answer_list, filters):
                     continue
                 matched_rows += 1
+                self._apply_metric_states(overall_metrics, metrics, answer_list)
+                if not dimensions:
+                    continue
                 group_payload = self._build_analyze_group_payload(answer_list, dimensions)
-                group_key = json.dumps(group_payload, ensure_ascii=False, sort_keys=True)
+                group_key = self._analysis_group_key(group_payload)
                 bucket = group_stats.get(group_key)
                 if bucket is None:
                     bucket = {
@@ -985,30 +1007,39 @@ class RecordTools(ToolBase):
                     group_stats[group_key] = bucket
                 bucket_metrics = cast(dict[str, JSONObject], bucket["metrics_state"])
                 self._apply_metric_states(bucket_metrics, metrics, answer_list)
-                self._apply_metric_states(overall_metrics, metrics, answer_list)
             if not has_more:
                 break
             current_page += 1
 
-        all_rows = [
-            {
-                "dimensions": cast(JSONObject, bucket["dimensions"]),
-                "metrics": self._render_metric_values(cast(dict[str, JSONObject], bucket["metrics_state"]), metrics),
-            }
-            for bucket in group_stats.values()
-        ]
-        all_rows = self._sort_analyze_rows(all_rows, sort, dimensions, metrics)
-        rows_truncated = len(all_rows) > limit
-        limited_rows = all_rows[:limit]
+        metric_totals = self._render_metric_values(overall_metrics, metrics)
+        if dimensions:
+            all_rows = [
+                {
+                    "dimensions": cast(JSONObject, bucket["dimensions"]),
+                    "metrics": self._render_metric_values(cast(dict[str, JSONObject], bucket["metrics_state"]), metrics),
+                }
+                for bucket in group_stats.values()
+            ]
+            all_rows = self._sort_analyze_rows(all_rows, sort, dimensions, metrics)
+            rows_truncated = len(all_rows) > limit
+            limited_rows = all_rows[:limit]
+            rows = limited_rows
+            rows_returned = len(limited_rows)
+            group_count = len(all_rows)
+            statement_scope = "returned_groups_only" if rows_truncated else "full_population"
+        else:
+            rows_truncated = False
+            rows = [{"dimensions": {}, "metrics": metric_totals}]
+            rows_returned = 1
+            group_count = 1
+            statement_scope = "full_population"
         raw_scan_complete = not has_more
         completeness_status = "complete" if raw_scan_complete else "incomplete"
         reason_code = "LOCAL_VIEW_FILTERING" if local_filtering and raw_scan_complete else ("SOURCE_EXHAUSTED" if raw_scan_complete else "SCAN_LIMIT_HIT")
-        totals_backend_count = None if local_filtering else result_amount
         totals = {
-            "backend_total_count": totals_backend_count,
             "scanned_count": matched_rows,
-            "group_count": len(all_rows) if dimensions else 1,
-            "metric_totals": self._render_metric_values(overall_metrics, metrics),
+            "group_count": group_count,
+            "metric_totals": metric_totals,
         }
         data: JSONObject = {
             "query": {
@@ -1043,7 +1074,7 @@ class RecordTools(ToolBase):
                 "applied_sort": [{"by": item["by"], "order": item["order"]} for item in sort],
                 "view": _view_selection_payload(view_selection),
             },
-            "rows": limited_rows if dimensions else [{"dimensions": {}, "metrics": totals["metric_totals"]}],
+            "rows": rows,
             "totals": totals,
             "completeness": {
                 "status": completeness_status,
@@ -1053,9 +1084,9 @@ class RecordTools(ToolBase):
             },
             "presentation": {
                 "row_limit": limit,
-                "rows_returned": 1 if not dimensions else len(limited_rows),
-                "rows_truncated": rows_truncated if dimensions else False,
-                "statement_scope": "returned_groups_only" if dimensions and rows_truncated else "full_population",
+                "rows_returned": rows_returned,
+                "rows_truncated": rows_truncated,
+                "statement_scope": statement_scope,
             },
             "warnings": self._build_analyze_warnings(local_filtering=local_filtering, rows_truncated=rows_truncated),
         }
@@ -1078,6 +1109,9 @@ class RecordTools(ToolBase):
             }
         if output_profile == "verbose":
             response["data"]["debug"] = {
+                "elapsed_ms": int((time.perf_counter() - started_at) * 1000),
+                "backend_total_hint": scan_control.get("backend_total_count", result_amount),
+                "backend_page_amount": scan_control.get("backend_page_amount"),
                 "source_pages": source_pages,
                 "raw_scan_complete": raw_scan_complete,
                 "scan_control": scan_control,
@@ -1110,6 +1144,16 @@ class RecordTools(ToolBase):
             }
         return states
 
+    def _analysis_group_key(self, payload: JSONObject) -> tuple[tuple[str, object], ...]:
+        return tuple((key, self._freeze_group_key_value(value)) for key, value in payload.items())
+
+    def _freeze_group_key_value(self, value: JSONValue) -> object:
+        if isinstance(value, dict):
+            return tuple((key, self._freeze_group_key_value(item)) for key, item in sorted(value.items()))
+        if isinstance(value, list):
+            return tuple(self._freeze_group_key_value(item) for item in value)
+        return value
+
     def _apply_metric_states(self, states: dict[str, JSONObject], metrics: list[JSONObject], answer_list: list[JSONValue]) -> None:
         for item in metrics:
             alias = cast(str, item["alias"])