@josephyan/qingflow-app-user-mcp 0.2.0-beta.999 → 1.0.5

package/README.md

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

package/package.json

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

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

@@ -4,10 +4,12 @@ For final statistics, grouped distributions, rankings, trends, or insight-style
 
 ## Record Reads
 
-- `record_list` is for browsing, export, and sample inspection only
+- For analysis-style reads, use `record_access` through [$qingflow-record-analysis](../../qingflow-record-analysis/SKILL.md)
+- `record_list` is for browsing and sample inspection only
 - `record_get` is for one exact record
 - Use `record_browse_schema_get` when field titles are uncertain instead of guessing ids
 - Do not present paged browse output as if it were a grouped or full-population conclusion
+- Use `record_export_direct` only when the user explicitly asks for export/download/Excel output
 
 ## Direct Writes
 

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

@@ -9,10 +9,11 @@ It is not a user-facing product spec. It exists to prevent skill drift.
 
 - Read range first with `app_get`, then `record_browse_schema_get(view_id=...)`
 - Standard flows:
-  - browse / export detail: `app_get -> record_browse_schema_get -> record_list / record_get`
+  - analyze: `app_get -> record_browse_schema_get -> record_access -> Python`
+  - browse detail: `app_get -> record_browse_schema_get -> record_list / record_get`
+  - explicit export/download/Excel: `view_get -> record_export_*` or `record_export_direct`
   - insert: `record_insert_schema_get -> record_insert`
   - update: `record_update_schema_get -> record_update`
-  - analyze: `app_get -> record_browse_schema_get -> record_analyze`
 
 ### Tasks
 
@@ -55,7 +56,7 @@ It is not a user-facing product spec. It exists to prevent skill drift.
 - Package public tools: do not regress to `package_create` / `package_attach_app` as the public default story
 - App editability: do not let `can_edit_form` imply app base-info writes
 - Portal and chart visibility: keep the public story on `portal_apply` / `app_charts_apply`, not low-level internal writes
-- Analysis fallback: standard path stays `record_analyze`, but complex tables may require explicit fallback modes
+- Analysis path: standard path stays `record_access -> Python`; `record_analyze` is a lightweight non-default helper
 
 ## Release Checklist For Skill Maintenance
 

package/skills/qingflow-record-analysis/SKILL.md

@@ -2,47 +2,48 @@
 name: qingflow-record-analysis
 description: Analyze Qingflow record data safely after the MCP is already connected and authenticated. Use when the user wants grouped distributions, ratios, averages, rankings, trends, insights, or any final statistical conclusion across an existing app's data. Do not use this skill for schema changes, app design, or ordinary record CRUD unless they are strictly supporting an analysis flow.
 metadata:
-  short-description: Analyze Qingflow record data with schema-first DSL execution
+  short-description: Analyze Qingflow record data with schema-first CSV access and Python
 ---
 
 # Qingflow Record Analysis
 
 This skill is for final statistical conclusions only.
 Assumes MCP is connected, authenticated, and on the correct workspace.
-Analysis tasks must start with `app_get`, then `record_browse_schema_get(view_id=...)`. Read top-level `fields` and `suggested_*`, then build field_id-based DSLs only.
-Analysis tasks must start with `record_browse_schema_get`.
-If `app_get.accessible_views` marks a view with `analysis_supported=false`, do not use that view for `record_list` or `record_analyze`. `boardView` and `ganttView` are special UI views, not list/analyze targets.
+Analysis tasks must start with `app_get`, then `record_browse_schema_get(view_id=...)`. Read top-level `fields` and `suggested_*`, then choose field_id-based columns and filters only.
+If `app_get.accessible_views` marks a view with `analysis_supported=false`, do not use that view for `record_access`, `record_list`, or `record_analyze`. `boardView` and `ganttView` are special UI views, not data-access targets.
 
-## Step 1: `app_get` → Step 2: `record_browse_schema_get(view_id=...)` → Step 3: build DSL → Step 4: `record_analyze`
+## Step 1: `app_get` → Step 2: `record_browse_schema_get(view_id=...)` → Step 3: `record_access` → Step 4: Python
 
-This is the ONLY execution order. Never skip `app_get` when the browse range is unclear. Never call `record_analyze` without a browse schema.
+This is the default execution order. Never skip `app_get` when the browse range is unclear. Never call `record_access` without a browse schema.
 
-Core tools: `app_get`, `record_browse_schema_get`, `record_analyze`. Use `record_list`/`record_get` only for post-analysis samples or an explicit fallback. Task/comment work stays in [$qingflow-task-ops](../qingflow-task-ops/SKILL.md).
+Core tools: `app_get`, `record_browse_schema_get`, `record_access`, Python. Use field_id-based DSLs only for columns, filters, sort clauses, and any optional lightweight `record_analyze` helper. Use `record_list`/`record_get` only for browse samples. Use `record_analyze` only as a lightweight non-default statistics helper when a compact grouped result is enough. Task/comment work stays in [$qingflow-task-ops](../qingflow-task-ops/SKILL.md).
 
 ## Execution Modes
 
 Choose the lightest mode that can still support a trustworthy conclusion:
 
-1. `server_aggregate`
+1. `client_python_from_record_access`
    - Default and preferred path
-   - Use `record_analyze` directly after `app_get -> record_browse_schema_get`
+   - Use `record_access` directly after `app_get -> record_browse_schema_get`
+   - Read CSV shard files from `files[].local_path` with Python
+   - Treat `complete=true` and `safe_for_final_conclusion=true` as required before giving a full-scope final conclusion
 
-2. `client_aggregate_from_record_list`
-   - Allowed fallback when `record_analyze` is unstable, unsupported on the target view, or the table is complex enough that service-side aggregation is not trustworthy
+2. `lightweight_record_analyze`
+   - Optional helper for small grouped summaries or quick sanity checks
    - Still requires `app_get -> record_browse_schema_get` first
-   - Use only after disclosing that the result is a fallback built from detail rows
+   - Do not make this the default agent path
 
 3. `cross_app_manual_reconcile`
    - Use when the question depends on joining multiple apps, organization-history alias mapping, or other business logic that current public tools do not express directly
-   - Be explicit that the conclusion is based on manual reconciliation rules, not one single DSL execution
+   - Be explicit that the conclusion is based on manual reconciliation rules, not one single app's CSV access
 
 ## Fallback Ladder
 
 Trigger a fallback when any of these are true:
 
-- `record_analyze` is unstable or cannot complete the scan reliably
-- the target view is unsupported for analysis
-- field semantics are ambiguous enough that a server aggregate would be misleading
+- `record_access` returns `complete=false`, `truncated=true`, or `safe_for_final_conclusion=false`
+- the target view is unsupported for data access
+- field semantics are ambiguous enough that local aggregation would be misleading
 - the question requires cross-app reconciliation
 - the question depends on organization-tree scope, historical department aliases, or other business rules that are not first-class MCP filters
 
@@ -58,6 +59,30 @@ When you fall back:
 
 ## DSL Contract
 
+### `record_access` Contract
+
+Use `record_access` to fetch detail rows into local CSV shards. It does not analyze, aggregate, or return large `items`.
+
+```json
+{
+  "app_key": "APP_KEY",
+  "view_id": "system:all",
+  "columns": [{ "field_id": 2 }, { "field_id": 18 }],
+  "where": [{ "field_id": 2, "op": "between", "value": ["2026-05-01", "2026-05-31"] }],
+  "order_by": [{ "field_id": 2, "direction": "asc" }]
+}
+```
+
+Then run Python against every `files[].local_path`. CSV columns are stable: `record_id`, then `field_<field_id>`. Use `fields[]` metadata to map titles and types.
+
+- Never ask for `page`, `page_size`, `limit`, or `max_rows`; `record_access` owns paging internally.
+- If multiple CSV files are returned, read them all.
+- If `complete=false` or `safe_for_final_conclusion=false`, downgrade the answer and disclose the limitation.
+- `record_export_direct` is only for explicit export/download/Excel requests, not default analysis.
+- QingBI/report reads are only for user-provided report URLs or `chart_id`; do not create or use reports as the default analysis path.
+
+### `record_analyze` Lightweight DSL
+
 ### DSL FORMAT (CRITICAL — read this FIRST)
 
 ### ✅ Correct vs ❌ Wrong — learn from these before building ANY DSL
@@ -143,7 +168,7 @@ Top-level arguments:
 - `strict_full`: `true` for final conclusions. `false` allows partial results.
 - `limit`: limits returned rows only, not scan scope.
 - `view_id`: the canonical browse selector. Prefer choosing it from `app_get.accessible_views`.
-- Prefer `view_id` entries where `analysis_supported=true`. If a view is `boardView` or `ganttView`, switch to a system or table-style custom view before calling `record_analyze`.
+- Prefer `view_id` entries where `analysis_supported=true`. If a view is `boardView` or `ganttView`, switch to a system or table-style custom view before calling `record_access` or `record_analyze`.
 - If a chosen `view_id` is `custom:*`, treat the output as analysis over an unverified saved-filter scope unless `verification.view_filter_verified=true`. For critical conclusions, prefer `system:all` plus explicit filters in the DSL.
 - `bucket` in dimensions: only for `suggested_time_fields`. Values: `day`/`week`/`month`/`quarter`/`year`/`null`.
 
@@ -163,8 +188,8 @@ Top-level arguments:
 - Final wording should stay as close as possible to schema titles.
 - Do not pass field titles, aliases, or guessed ids.
 - If `completeness.statement_scope=returned_groups_only` or `completeness.rows_truncated=true`, downgrade wording to returned groups only.
-- One DSL per question. Multiple small DSLs > one overloaded request.
-- `record_list` is not the default basis for final statistics. Use it only in an explicit fallback mode and disclose that fallback in the final answer.
+- One data-access request per coherent dataset. Multiple small Python computations over the same CSV files are fine.
+- `record_list` is not the basis for final statistics. Use it only for browse/sample inspection and disclose that scope if quoted.
 - Set `alias` for any metric you will sort by, compare, or quote.
 
 ---
@@ -172,14 +197,14 @@ Top-level arguments:
 ## OUTPUT
 
 - Final answer must show concrete numbers.
-- Final answer must state which execution mode was used whenever the answer is not a straightforward `server_aggregate`
+- Final answer must state which execution mode was used whenever the answer is not the default `client_python_from_record_access`
 - If `result.rows` exists, list each returned row; if there are more than 20 rows, show Top 20 and say so.
 - 占比 = 行指标值 / `result.totals.metric_totals` 总值；如 `metric_totals` 缺失，用各行之和作分母。
 - Prefer the structured `ranking` block when it exists.
 - `safe_for_final_conclusion=true` → `全量可信结论`
 - Otherwise → `初步观察`
 - `rows_truncated=true` → 用 `前 N 个分组`, 不用 `全部`/`所有`
-- If you used a fallback mode, explicitly disclose:
+- If you used a fallback mode or `record_access.safe_for_final_conclusion=false`, explicitly disclose:
   - whether this is full-scope or a manually curated subset
   - which time field was used
   - which organization scope was used

package/skills/qingflow-record-analysis/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Qingflow Record Analysis"
   short_description: "Analyze Qingflow record data with schema-first DSL execution"
-  default_prompt: "Use $qingflow-record-analysis for grouped distributions, ratios, rankings, trends, and final statistical conclusions in Qingflow apps. Start with record_browse_schema_get, build one or more field_id-based DSLs, then run record_analyze. Treat record_list as sample-only when capped or paged, and separate full conclusions from sample observations."
+  default_prompt: "Use $qingflow-record-analysis for grouped distributions, ratios, rankings, trends, and final statistical conclusions in Qingflow apps. Start with app_get and record_browse_schema_get, run record_access with field_id-based columns/where/order_by, then analyze the returned CSV shard files with Python. Treat record_list as sample-only and record_analyze as a lightweight non-default helper."

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

@@ -2,14 +2,15 @@
 
 ## Do not skip schema
 
-If the task is analysis-style and you jump straight to `record_list` or `record_analyze`, you are already off the stable path.
+If the task is analysis-style and you jump straight to `record_list`, `record_export_direct`, or `record_analyze`, you are already off the stable path.
 
 Correct recovery:
 
-1. `record_browse_schema_get`
-2. inspect the schema and choose fields
-3. build one or more small DSLs
-4. run `record_analyze`
+1. `app_get`
+2. `record_browse_schema_get`
+3. inspect the schema and choose fields
+4. run `record_access`
+5. use Python over the returned CSV shards
 
 The schema here is applicant-node visible-only. If a field is absent, treat it as not available to the current user rather than switching to guessed ids or builder-side memory.
 
@@ -23,7 +24,7 @@ Examples:
 
 Do not pass vague time phrases or impossible dates into MCP.
 
-## Do not treat 200-row list output as full data
+## Do not treat paged list output as full data
 
 `record_list` can hit:
 
@@ -44,7 +45,7 @@ It is not acceptable to use that result alone for:
 
 ## Do not mix full analyze totals with sample rows
 
-If `record_analyze` gives full-population coverage, but list rows are capped, do not merge them into one final statement.
+If `record_access` or `record_analyze` gives full-population coverage, but list rows are capped, do not merge them into one final statement.
 
 Split them into:
 
@@ -88,17 +89,18 @@ Examples of the right recovery question:
 
 ## Do not try to control paging manually
 
-`record_analyze` hides paging and scan budget on purpose.
+`record_access` and `record_analyze` hide paging and scan budget on purpose.
 
 - Do not invent `page_size`
 - Do not invent `requested_pages`
 - Do not invent `scan_max_pages`
 - Do not invent `auto_expand_pages`
+- Do not invent `max_rows`
 
 When the result is incomplete:
 
 1. narrow the scope with views or filters
-2. reduce the analysis problem into smaller DSLs
+2. reduce the analysis problem into smaller field_id-based access requests
 3. keep the answer at `初步观察` or `部分结果` if completeness is still not enough
 
 ## Do not guess metric semantics from loose business wording

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

@@ -15,11 +15,33 @@ Use this skill when the user asks for:
 
 ## Canonical analysis sequence
 
-1. `record_browse_schema_get`
-2. decide whether the question needs `count`, `sum`, `avg`, `distinct_count`, `ratio`, or `ranking`
-3. build one or more field_id-based DSLs
-4. `record_analyze`
-5. `record_list` only for sample inspection
+1. `app_get`
+2. `record_browse_schema_get`
+3. decide whether the question needs `count`, `sum`, `avg`, `distinct_count`, `ratio`, or `ranking`
+4. choose field_id-based `columns`, `where`, and `order_by`
+5. `record_access`
+6. Python over every returned CSV shard
+7. `record_list` only for sample inspection
+
+Result reading order:
+
+1. `record_access.complete`
+2. `record_access.safe_for_final_conclusion`
+3. `record_access.files[].local_path`
+4. Python outputs
+5. `record_access.fields`
+6. `record_access.warnings`
+
+Treat `record_browse_schema_get` as the browse-schema source of truth. Missing fields are permission boundaries, not invitations to guess hidden ids.
+
+## Lightweight `record_analyze` helper sequence
+
+1. `app_get`
+2. `record_browse_schema_get`
+3. decide whether the question needs `count`, `sum`, `avg`, `distinct_count`, `ratio`, or `ranking`
+4. build one or more field_id-based DSLs
+5. `record_analyze`
+6. `record_list` only for sample inspection
 
 Result reading order:
 
@@ -30,7 +52,7 @@ Result reading order:
 5. `completeness`
 6. `presentation`
 
-Treat `record_browse_schema_get` as the browse-schema source of truth. Missing fields are permission boundaries, not invitations to guess hidden ids.
+Use this only when a compact grouped result is enough; it is not the default path.
 
 ## Distribution / ratio pattern
 
@@ -41,7 +63,8 @@ Treat `record_browse_schema_get` as the browse-schema source of truth. Missing f
    - one dimension
    - `count`
    - sort by the count alias
-5. Run `record_analyze`
+5. Run `record_access`
+6. Use Python to group the CSV rows
 6. Report:
    - `result.totals.metric_totals`
    - `safe_for_final_conclusion`
@@ -56,20 +79,18 @@ Treat `record_browse_schema_get` as the browse-schema source of truth. Missing f
    - numerator
    - denominator
    - grouping dimension, if any
-3. Build separate DSLs when numerator and denominator are not the same filtered population
+3. Build separate `record_access` requests when numerator and denominator are not the same filtered population
 4. Query the numerator first
 5. Query the denominator second
-6. Only compute the ratio outside MCP after both source results are complete and use compatible scopes
+6. Only compute the ratio in Python after both source results are complete and use compatible scopes
 7. If the denominator is missing, do not call the output `渗透率`, `转化率`, `占比`, or `%`
 
 ## Average / ranking pattern
 
 1. Run `record_browse_schema_get`
 2. Choose one dimension field and one numeric metric field
-3. Build a DSL with:
-   - `dimensions=[...]`
-   - `metrics=[count,sum]` or `metrics=[count,avg,min,max]`
-4. Run `record_analyze`
+3. Fetch the dimension and numeric metric fields with `record_access`
+4. Use Python for grouped `count/sum/avg/min/max`
 5. If the answer uses ranking language, make the ranking come from structured sorted results
 6. Prefer the structured `ranking` block when it exists instead of inferring order from loose text
 7. Use list mode only to inspect examples after the aggregate result is understood
@@ -78,14 +99,14 @@ Treat `record_browse_schema_get` as the browse-schema source of truth. Missing f
 
 1. Run `record_browse_schema_get`
 2. Choose a date/time field from `suggested_time_fields`
-3. Build a DSL with `bucket=day|week|month|quarter|year`
-4. Run `record_analyze`
+3. Fetch the date/time field and needed metric fields with `record_access`
+4. Use Python to bucket by day/week/month/quarter/year
 5. Treat the result as final only if `safe_for_final_conclusion=true`
 6. If the user asked for a relative time phrase such as `最近一个完整自然月`, translate it into an explicit legal date range before building the DSL
 
 ## Sample inspection pattern
 
-Only use `record_list` after schema/analyze when you need:
+Only use `record_list` after schema/access when you need:
 
 - example rows
 - spot checks

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

@@ -13,7 +13,7 @@ When analysis is intended as a final answer, use this order:
 Only write `全量可信结论` when:
 
 - `record_browse_schema_get` was used
-- the analysis path used one or more `record_analyze` calls
+- the analysis path used `record_access` and Python, or an explicitly chosen lightweight `record_analyze` helper
 - every key analysis result has `safe_for_final_conclusion=true`
 - `safe_for_final_conclusion=true is necessary but not sufficient`
 - no key result depends on an invalid time phrase, an undefined denominator, or an unsupported derived metric
@@ -27,6 +27,7 @@ Put evidence into `样本观察` when:
 - the tool reports `row_cap_hit`
 - the tool reports `sample_only`
 - the result is compact/capped and not complete
+- `record_access.complete=false` or `record_access.truncated=true`
 
 ## Downgrade rule
 
@@ -37,6 +38,7 @@ If `record_browse_schema_get` was not used for an analysis task, downgrade the o
 Do not combine:
 
 - full totals from `record_analyze`
+- full CSV-derived conclusions from `record_access`
 - sample-only details from `record_list`
 
 into one sentence like “基于全部数据分析...”.

package/src/qingflow_mcp/__init__.py

@@ -5,7 +5,7 @@ from pathlib import Path
 
 __all__ = ["__version__"]
 
-_FALLBACK_VERSION = "0.2.0b999"
+_FALLBACK_VERSION = "0.2.0b1017"
 
 
 def _resolve_local_pyproject_version() -> str | None:

package/src/qingflow_mcp/backend_client.py

@@ -474,6 +474,115 @@ class BackendClient:
                 pass
         return import_result
 
+    def start_socket_record_export(
+        self,
+        context: BackendRequestContext,
+        *,
+        app_key: str,
+        view_id: str,
+        filter_bean: JSONObject,
+        export_config: JSONObject,
+        view_key: str | None = None,
+        result_amount: int = 0,
+        ack_timeout_seconds: float = 8.0,
+    ) -> dict[str, Any]:
+        try:
+            import socketio  # type: ignore[import-not-found]
+        except ImportError as exc:
+            raise QingflowApiError(
+                category="config",
+                message=f"socket.io client dependency is missing: {exc}",
+            )
+
+        socket_base_url = self._build_socket_base_url(context.base_url)
+        export_result: dict[str, Any] = {
+            "backend_export_id": None,
+            "warnings": [],
+        }
+        sio = socketio.Client(reconnection=False, logger=False, engineio_logger=False)
+        event_name = "excelViewgraph" if view_key else "excel"
+        event_args: tuple[Any, ...]
+        if view_key:
+            event_args = (
+                context.token,
+                None,
+                view_key,
+                filter_bean,
+                export_config,
+                int(result_amount),
+            )
+        else:
+            event_args = (
+                context.token,
+                app_key,
+                filter_bean,
+                export_config,
+                int(result_amount),
+            )
+        try:
+            sio.connect(
+                socket_base_url,
+                transports=["websocket"],
+                socketio_path="socket.io",
+                headers=self._base_headers(
+                    context.token,
+                    context.ws_id,
+                    qf_version=context.qf_version,
+                ),
+                wait_timeout=ack_timeout_seconds,
+            )
+            sio.emit("token", context.token)
+            sleep(0.2)
+            ack = sio.call(
+                event_name,
+                event_args,
+                timeout=ack_timeout_seconds,
+            )
+            ack_payload = ack[0] if isinstance(ack, list) and ack else ack
+            export_id: Any = ack_payload
+            if isinstance(ack_payload, dict):
+                error_code = ack_payload.get("error")
+                ack_message = ack_payload.get("message")
+                export_id = ack_payload.get("data")
+                if isinstance(export_id, dict):
+                    export_id = (
+                        export_id.get("exportId")
+                        or export_id.get("export_id")
+                        or export_id.get("id")
+                    )
+                if error_code not in (None, 0):
+                    raise QingflowApiError(
+                        category="backend",
+                        message=str(ack_message or f"socket export rejected with error {error_code}"),
+                        details={
+                            "socket_error_code": error_code,
+                            "app_key": app_key,
+                            "view_id": view_id,
+                            "view_key": view_key,
+                        },
+                    )
+            if not export_id:
+                raise QingflowApiError(category="backend", message="socket export ack did not return export_id")
+            export_result["backend_export_id"] = str(export_id)
+        except Exception as exc:
+            message = str(exc)
+            if "timeout" in message.lower():
+                raise QingflowApiError(
+                    category="network",
+                    message="socket export ack timed out",
+                    details={"error_code": "EXPORT_SOCKET_ACK_TIMEOUT"},
+                )
+            if isinstance(exc, QingflowApiError):
+                raise
+            raise QingflowApiError(category="network", message=message or "socket export failed")
+        finally:
+            try:
+                if sio.connected:
+                    sio.disconnect()
+            except Exception:
+                pass
+        return export_result
+
     def _request_with_meta(
         self,
         method: str,