@josephyan/qingflow-app-user-mcp 0.2.0-beta.40 → 0.2.0-beta.42

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "0.2.0-beta.40",
+  "version": "0.2.0-beta.42",
   "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.0b40"
+version = "0.2.0b42"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"
@@ -26,8 +26,10 @@ dependencies = [
   "mcp>=1.9.4,<2.0.0",
   "httpx>=0.27,<1.0",
   "keyring>=25.5,<26.0",
+  "openpyxl>=3.1,<4.0",
   "pydantic>=2.8,<3.0",
   "pycryptodome>=3.20,<4.0",
+  "python-socketio[client]>=5.11,<6.0",
 ]
 
 [project.optional-dependencies]

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

@@ -16,7 +16,7 @@ Assumes MCP is connected, authenticated, and on the correct workspace.
 
 Route to exactly one of these specialized paths:
 
-1. Record CRUD  
+1. Record CRUD and import  
    Switch to [$qingflow-record-crud](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-crud/SKILL.md)
 
 2. Task workflow operations  
@@ -32,7 +32,7 @@ Route to exactly one of these specialized paths:
 
 - If the user does not know the target `app_key`, discover apps first with `app_list` or `app_search`, then route to the specialized skill
 - If the app is known but the available data range is unclear, call `app_get` first and inspect `accessible_views`
-- If the task is about browsing, reading, creating, updating, deleting, attachments, relations, subtable writes, or member/department-field candidate lookup, switch to `$qingflow-record-crud`
+- If the task is about browsing, reading, creating, updating, deleting, attachments, relations, subtable writes, member/department-field candidate lookup, import templates, import-file verification, authorized local file repair, import execution, or import status, switch to `$qingflow-record-crud`
 - 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 grouped distributions, ratios, rankings, trends, insights, or any final statistical conclusion, switch to `$qingflow-record-analysis`
 - If the MCP is not connected, authenticated, or bound to the right workspace, switch to `$qingflow-mcp-setup`
@@ -42,6 +42,7 @@ Route to exactly one of these specialized paths:
 - prefer canonical app ids, record ids, task ids, and workflow node ids over guessed names
 - if a field or target is still ambiguous after schema/task lookup, ask the user to confirm from a short candidate list instead of guessing
 - if the task can stay read-only, do not write or act
+- if the task involves a user-uploaded import file, do not modify the file unless the user explicitly authorizes repair or normalization
 - if the current MCP capability is unsupported, the workflow is awkward, or the user's need still cannot be satisfied after reasonable use, summarize the gap, ask whether to submit feedback, and call `feedback_submit` only after explicit user confirmation
 
 ## Shared Helper

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

@@ -109,6 +109,7 @@ Top-level arguments:
 - `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`.
+- 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`.
 
 ---

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

@@ -1,8 +1,8 @@
 ---
 name: qingflow-record-crud
-description: Browse, read, create, update, and delete Qingflow records after the MCP is already connected and authenticated. Use when the user wants schema-first record CRUD with SQL-like JSON DSL. Do not use this skill for task-center workflow actions or final statistical analysis.
+description: Browse, read, create, update, delete, and import Qingflow records after the MCP is already connected and authenticated. Use when the user wants schema-first record CRUD, import-template verification/import execution, or SQL-like JSON DSL writes. Do not use this skill for task-center workflow actions or final statistical analysis.
 metadata:
-  short-description: Schema-first Qingflow record CRUD
+  short-description: Schema-first Qingflow record CRUD and import
 ---
 
 # Qingflow Record CRUD
@@ -19,6 +19,7 @@ Use exactly one of these default paths:
 1. Browse records: `app_get -> record_schema_get(schema_mode="browse", view_id=...) -> record_list`
 2. Read one record: `app_get -> record_schema_get(schema_mode="browse", view_id=...) -> record_get`
 3. Write records: `record_schema_get(schema_mode="applicant") -> record_write`
+4. Import records: `record_import_template_get -> record_import_verify -> (optional authorized file repair) -> record_import_start -> record_import_status_get`
 
 ## Core Tools
 
@@ -26,6 +27,11 @@ Use exactly one of these default paths:
 - `record_list`
 - `record_get`
 - `record_write`
+- `record_import_template_get`
+- `record_import_verify`
+- `record_import_repair_local`
+- `record_import_start`
+- `record_import_status_get`
 
 `record_schema_get(schema_mode="applicant")` exposes the current user's applicant-node visible write/create fields.
 `record_schema_get(schema_mode="browse", view_id=...)` exposes browse-schema fields for the selected accessible view.
@@ -56,11 +62,12 @@ Use `record_member_candidates` / `record_department_candidates` as the default l
 5. If browse/read range is unclear, run `app_get` and choose from `accessible_views`
 6. Run `record_schema_get(schema_mode="browse", view_id=...)` before browse/read
 7. Run `record_schema_get(schema_mode="applicant")` before write
-6. If the request is analysis-like, switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)
-7. If the request is write-like, decide `insert / update / delete` before building any payload
-8. If fields are still ambiguous after `record_schema_get`, ask the user to confirm from a short candidate list instead of guessing
-9. For high-risk writes or production changes, read the current state first whenever practical
-10. After actions, report the affected `record_id`, counts, or returned item count
+8. If the request is import-like, decide whether the user needs template download, file verification, file repair, import execution, or import status before changing any file
+9. If the request is analysis-like, switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)
+10. If the request is write-like, decide `insert / update / delete` before building any payload
+11. If fields are still ambiguous after `record_schema_get`, ask the user to confirm from a short candidate list instead of guessing
+12. For high-risk writes or production changes, read the current state first whenever practical
+13. After actions, report the affected `record_id`, counts, or returned item count
 
 ## Record Read Rules
 
@@ -124,9 +131,38 @@ The DSL is clause-shaped like SQL, but it is **not raw SQL text**.
 - `relation`: `✅ {"field_id":25,"value":{"apply_id":5001}}` / `❌ {"field_id":25,"value":"客户A"}`
 - `attachment`: upload first, then `✅ {"field_id":13,"value":{"value":"https://.../a.pdf","name":"a.pdf"}}` / `❌ {"field_id":13,"value":"/tmp/a.pdf"}`
 
+## Import Rules
+
+Use the import tools for file-based bulk data loading, not `record_write`.
+
+### Import workflow
+
+1. Get the official template with `record_import_template_get`
+2. Verify the uploaded file with `record_import_verify`
+3. If verification fails, explain the issues first
+4. Only modify the uploaded file if the user explicitly authorizes repair or normalization
+5. If authorized, preserve the original file and write a repaired copy instead of overwriting the source file by default
+6. Use `record_import_repair_local` for authorized `.xlsx` repair
+7. Re-run `record_import_verify` on the repaired copy
+8. Start import only from a successful verification result
+9. Track the job with `record_import_status_get`
+
+### Import discipline
+
+- Do not modify a user-uploaded Excel or CSV file unless the user explicitly authorizes file repair
+- Do not silently normalize, rename, reorder, or delete columns
+- Do not fabricate business values to satisfy validation
+- Only fix format-level issues that keep the user’s intended data semantics intact, such as header alignment, date/number formatting, enum spelling aligned to the template, blank trailing rows, workbook sheet shape, or attachment/url cell normalization
+- If a repair would change business meaning or requires guessing missing values, stop and ask the user instead of editing the file
+- After any authorized repair, report exactly what changed and which file path is the repaired import candidate
+- Do not start import unless the repaired file passes `record_import_verify`
+- `record_import_start` must receive an explicit `being_enter_auditing` choice; do not assume a default import mode
+
 ## Response Interpretation
 
 - `record_list` returns browse/sample data, not final analysis conclusions
+- If `view_id` is a custom view, treat the result as convenience browse output only when `warnings` includes `CUSTOM_VIEW_FILTER_UNVERIFIED`. In that case do not state the saved filter result as a verified fact.
+- Prefer `system:all` plus explicit `where` filters whenever the user needs a trustworthy scoped dataset.
 - `record_write` always performs internal static preflight before any apply
 - If `record_write` returns `ok=false`, the write was blocked and not executed
 - Prefer explaining `field_errors` before summarizing top-level blockers

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

@@ -128,3 +128,19 @@ If the payload includes them, stop after the blocked `record_write` response and
 ```json
 { "field_id": 13, "value": { "value": "https://.../a.pdf", "name": "a.pdf" } }
 ```
+
+## Import Pattern
+
+Use `record_import_template_get -> record_import_verify -> record_import_repair_local -> record_import_start -> record_import_status_get` when file repair is authorized; otherwise skip the repair step.
+
+If verification fails:
+
+1. summarize the validation issues first
+2. do not modify the uploaded file unless the user explicitly authorizes repair
+3. if authorized, preserve the original file and create a repaired copy
+4. only repair format-level problems that do not require guessing business meaning
+5. use `record_import_repair_local` only after explicit authorization and only for safe format repairs
+6. re-run `record_import_verify`
+7. import only after verification passes, and pass an explicit `being_enter_auditing` choice to `record_import_start`
+
+Do not silently "fix" business data to force an import through.

package/skills/qingflow-task-ops/SKILL.md

@@ -97,6 +97,9 @@ Use exactly one of these default paths:
 - Do not execute `task_action_execute` until the user explicitly confirms the chosen action
 - Avoid actions on ambiguous tasks or records
 - Summarize the final action and the exact `app_key / record_id / workflow_node_id`
+- `task_action_execute` now distinguishes action execution from workflow continuation. Read `verification.runtime_continuation_verified` before claiming the workflow actually moved on.
+- If `task_action_execute` returns `partial_success` with `WORKFLOW_CONTINUATION_UNVERIFIED`, report the action as sent but the downstream continuation as unverified.
+- If `task_action_execute` returns `TASK_CONTEXT_VISIBILITY_UNVERIFIED` after a `46001`-style context loss, do not claim the task was already processed unless the workflow log or record state proves it.
 
 ## Feedback Escalation
 

package/src/qingflow_mcp/__init__.py

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

package/src/qingflow_mcp/backend_client.py

@@ -1,6 +1,9 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+from threading import Event
+from typing import Any
+from urllib.parse import urlsplit, urlunsplit
 from uuid import uuid4
 
 import httpx
@@ -201,6 +204,182 @@ class BackendClient:
             "body": body,
         }
 
+    def download_binary(self, url: str, *, headers: dict[str, str] | None = None) -> bytes:
+        try:
+            response = self._client.get(url, headers=headers or None)
+        except httpx.RequestError as exc:
+            raise QingflowApiError(category="network", message=str(exc))
+        if response.status_code >= 400:
+            raise QingflowApiError(
+                category="http",
+                message=self._extract_message(response.text) or f"HTTP {response.status_code}",
+                http_status=response.status_code,
+            )
+        return response.content
+
+    def request_multipart(
+        self,
+        method: str,
+        context: BackendRequestContext,
+        path: str,
+        *,
+        data: dict[str, Any] | None = None,
+        files: dict[str, tuple[str, bytes, str | None]] | None = None,
+        unwrap: bool = True,
+    ) -> JSONValue:
+        return self.request_multipart_with_meta(
+            method,
+            context,
+            path,
+            data=data,
+            files=files,
+            unwrap=unwrap,
+        ).data
+
+    def request_multipart_with_meta(
+        self,
+        method: str,
+        context: BackendRequestContext,
+        path: str,
+        *,
+        data: dict[str, Any] | None = None,
+        files: dict[str, tuple[str, bytes, str | None]] | None = None,
+        unwrap: bool = True,
+    ) -> BackendResponse:
+        headers = self._base_headers(
+            context.token,
+            context.ws_id,
+            context.qf_request_id,
+            qf_version=context.qf_version,
+        )
+        request_files: dict[str, tuple[str, bytes, str | None]] | None = None
+        if files:
+            request_files = {key: value for key, value in files.items()}
+        try:
+            response = self._client.request(
+                method.upper(),
+                self._build_url(context.base_url, path),
+                data=data,
+                files=request_files,
+                headers=headers,
+            )
+        except httpx.RequestError as exc:
+            raise QingflowApiError(category="network", message=str(exc), request_id=headers["Qf-Request-Id"])
+        parsed = self._parse_response(response, headers["Qf-Request-Id"], unwrap=unwrap)
+        return BackendResponse(
+            data=parsed,
+            headers=dict(response.headers),
+            request_id=headers["Qf-Request-Id"],
+            http_status=response.status_code,
+            qf_response_version=self._extract_response_qf_version(response.headers),
+        )
+
+    def start_socket_data_import(
+        self,
+        context: BackendRequestContext,
+        *,
+        app_key: str,
+        being_enter_auditing: bool,
+        view_key: str | None,
+        excel_url: str,
+        excel_name: str,
+        ack_timeout_seconds: float = 8.0,
+        initial_wait_seconds: float = 4.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)
+        import_result: dict[str, Any] = {
+            "import_id": None,
+            "process_id_str": None,
+            "status": "accepted",
+            "warnings": [],
+            "initial_event": None,
+            "failure_event": None,
+        }
+        initial_event_received = Event()
+        failure_event_received = Event()
+        sio = socketio.Client(reconnection=False, logger=False, engineio_logger=False)
+
+        def _handle_initial(payload: Any) -> None:
+            if isinstance(payload, dict):
+                import_result["initial_event"] = payload
+                process_id = payload.get("processIdStr") or payload.get("process_id_str") or payload.get("processId")
+                if process_id is not None:
+                    import_result["process_id_str"] = str(process_id)
+            initial_event_received.set()
+
+        def _handle_failure(payload: Any) -> None:
+            if isinstance(payload, dict):
+                import_result["failure_event"] = payload
+                process_id = payload.get("processIdStr") or payload.get("process_id_str") or payload.get("processId")
+                if process_id is not None:
+                    import_result["process_id_str"] = str(process_id)
+            failure_event_received.set()
+
+        try:
+            sio.connect(
+                socket_base_url,
+                transports=["polling", "websocket"],
+                socketio_path="socket.io",
+                headers=self._base_headers(
+                    context.token,
+                    context.ws_id,
+                    qf_version=context.qf_version,
+                ),
+                wait_timeout=ack_timeout_seconds,
+            )
+            ack = sio.call(
+                "dataImport",
+                [
+                    context.token,
+                    app_key,
+                    bool(being_enter_auditing),
+                    view_key,
+                    False,
+                    excel_url,
+                    excel_name,
+                ],
+                timeout=ack_timeout_seconds,
+            )
+            import_id = ack[0] if isinstance(ack, list) and ack else ack
+            if not import_id:
+                raise QingflowApiError(category="backend", message="socket import ack did not return import_id")
+            import_result["import_id"] = str(import_id)
+            sio.on(f"dataImportRes_{import_result['import_id']}", _handle_initial)
+            sio.on(f"dataImportFail_{import_result['import_id']}", _handle_failure)
+            if not initial_event_received.wait(timeout=initial_wait_seconds) and not failure_event_received.wait(timeout=0.1):
+                import_result["warnings"].append(
+                    {
+                        "code": "IMPORT_SOCKET_INITIAL_EVENT_PENDING",
+                        "message": "Import ack received, but no initial progress payload arrived within the initial wait window.",
+                    }
+                )
+        except Exception as exc:
+            message = str(exc)
+            if "timeout" in message.lower():
+                raise QingflowApiError(
+                    category="network",
+                    message="socket import ack timed out",
+                    details={"error_code": "IMPORT_SOCKET_ACK_TIMEOUT"},
+                )
+            if isinstance(exc, QingflowApiError):
+                raise
+            raise QingflowApiError(category="network", message=message or "socket import failed")
+        finally:
+            try:
+                if sio.connected:
+                    sio.disconnect()
+            except Exception:
+                pass
+        return import_result
+
     def _request_with_meta(
         self,
         method: str,
@@ -334,3 +513,13 @@ class BackendClient:
         if not normalized:
             raise QingflowApiError.config_error("base_url is required")
         return f"{normalized}/{path.lstrip('/')}"
+
+    def _build_socket_base_url(self, base_url: str) -> str:
+        normalized = normalize_base_url(base_url)
+        if not normalized:
+            raise QingflowApiError.config_error("base_url is required")
+        parsed = urlsplit(normalized)
+        path = parsed.path.rstrip("/")
+        if path.endswith("/api"):
+            path = path[:-4]
+        return urlunsplit((parsed.scheme, parsed.netloc, path or "", "", ""))

package/src/qingflow_mcp/builder_facade/models.py

@@ -266,6 +266,8 @@ class FieldPatch(StrictModel):
     description: str | None = None
     options: list[str] = Field(default_factory=list)
     target_app_key: str | None = None
+    display_field: FieldSelector | None = None
+    visible_fields: list[FieldSelector] = Field(default_factory=list)
     subfields: list["FieldPatch"] = Field(default_factory=list)
 
     @model_validator(mode="after")
@@ -274,6 +276,8 @@ class FieldPatch(StrictModel):
             raise ValueError("relation field requires target_app_key")
         if self.type != PublicFieldType.relation and self.target_app_key:
             raise ValueError("target_app_key is only allowed for relation fields")
+        if self.type != PublicFieldType.relation and (self.display_field is not None or self.visible_fields):
+            raise ValueError("display_field and visible_fields are only allowed for relation fields")
         if self.type == PublicFieldType.subtable and not self.subfields:
             raise ValueError("subtable field requires subfields")
         if self.type != PublicFieldType.subtable and self.subfields:
@@ -293,12 +297,16 @@ class FieldMutation(StrictModel):
     description: str | None = None
     options: list[str] | None = None
     target_app_key: str | None = None
+    display_field: FieldSelector | None = None
+    visible_fields: list[FieldSelector] | None = None
     subfields: list[FieldPatch] | None = None
 
     @model_validator(mode="after")
     def validate_shape(self) -> "FieldMutation":
         if self.type == PublicFieldType.relation and not self.target_app_key:
             raise ValueError("relation field requires target_app_key")
+        if self.type is not None and self.type != PublicFieldType.relation and (self.display_field is not None or self.visible_fields):
+            raise ValueError("display_field and visible_fields are only allowed for relation fields")
         if self.type == PublicFieldType.subtable and not self.subfields:
             raise ValueError("subtable field requires subfields")
         return self