@qingflow-tech/qingflow-app-builder-mcp 1.0.3 → 1.0.5

package/src/qingflow_mcp/cli/commands/workspace.py

@@ -3,6 +3,9 @@ from __future__ import annotations
 import argparse
 
 from ..context import CliContext
+from ..interaction import cancelled_result, resolve_interactive_selection
+from ..terminal_ui import SelectionOption
+from .common import raise_config_error
 
 
 def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
@@ -20,8 +23,8 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     get_parser.set_defaults(handler=_handle_get, format_hint="workspace_get")
 
     select_parser = workspace_subparsers.add_parser("select", help="切换当前工作区")
-    select_parser.add_argument("--ws-id", type=int, required=True)
-    select_parser.set_defaults(handler=_handle_select, format_hint="workspace_get")
+    select_parser.add_argument("--ws-id", type=int, default=0, help="不传时在交互终端中选择工作区")
+    select_parser.set_defaults(handler=_handle_select, format_hint="workspace_select")
 
 
 def _handle_list(args: argparse.Namespace, context: CliContext) -> dict:
@@ -41,7 +44,66 @@ def _handle_get(args: argparse.Namespace, context: CliContext) -> dict:
 
 
 def _handle_select(args: argparse.Namespace, context: CliContext) -> dict:
+    if int(args.ws_id or 0) <= 0:
+        selection = _choose_workspace_interactively(args, context)
+        if selection.status == "unavailable":
+            raise_config_error(
+                "workspace select requires --ws-id, or an interactive terminal to choose a workspace",
+                fix_hint="Retry in an interactive terminal, or pass `--ws-id WS_ID` explicitly.",
+            )
+        if selection.status == "empty":
+            raise_config_error(
+                selection.message or "workspace select could not open a selector because no workspaces are available.",
+                fix_hint="Run `workspace list` to confirm visible workspaces, or retry with `--ws-id WS_ID`.",
+            )
+        if selection.status == "cancelled":
+            return cancelled_result(selection.message or "已取消")
+        args.ws_id = int(selection.value or 0)
     return context.workspace.workspace_select(
         profile=args.profile,
         ws_id=int(args.ws_id),
     )
+
+
+def _choose_workspace_interactively(args: argparse.Namespace, context: CliContext):
+    current_ws_id = None
+    sessions = getattr(context, "sessions", None)
+    if sessions is not None and hasattr(sessions, "get_profile"):
+        try:
+            session_profile = sessions.get_profile(args.profile)
+        except Exception:
+            session_profile = None
+        current_ws_id = getattr(session_profile, "selected_ws_id", None) if session_profile is not None else None
+    def load_options() -> list[SelectionOption[int]]:
+        page = context.workspace.workspace_list(
+            profile=args.profile,
+            page_num=1,
+            page_size=100,
+            include_external=False,
+        ).get("page")
+        items = page.get("list") if isinstance(page, dict) and isinstance(page.get("list"), list) else []
+        options: list[SelectionOption[int]] = []
+        for item in items:
+            if not isinstance(item, dict):
+                continue
+            ws_id = int(item.get("wsId") or 0)
+            if ws_id <= 0:
+                continue
+            workspace_name = str(item.get("workspaceName") or item.get("wsName") or f"Workspace {ws_id}")
+            remark = str(item.get("remark") or "").strip()
+            label = workspace_name
+            if remark:
+                label = f"{workspace_name} - {remark}"
+            hint = f"ws_id={ws_id}"
+            if current_ws_id == ws_id:
+                hint += " · 当前"
+            options.append(SelectionOption(value=ws_id, label=label, hint=hint))
+        return options
+
+    return resolve_interactive_selection(
+        args,
+        title="选择工作区",
+        unavailable_message="workspace select requires --ws-id, or an interactive terminal to choose a workspace",
+        empty_message="workspace select could not open a selector because no visible workspaces were returned.",
+        load_options=load_options,
+    )

package/src/qingflow_mcp/cli/context.py

@@ -8,6 +8,7 @@ from ..tools.ai_builder_tools import AiBuilderTools
 from ..tools.app_tools import AppTools
 from ..tools.auth_tools import AuthTools
 from ..tools.code_block_tools import CodeBlockTools
+from ..tools.export_tools import ExportTools
 from ..tools.feedback_tools import FeedbackTools
 from ..tools.file_tools import FileTools
 from ..tools.import_tools import ImportTools
@@ -29,6 +30,7 @@ class CliContext:
     record: RecordTools
     code_block: CodeBlockTools
     imports: ImportTools
+    exports: ExportTools
     task: TaskContextTools
     files: FileTools
     builder_feedback: FeedbackTools
@@ -52,6 +54,7 @@ def build_cli_context() -> CliContext:
         record=RecordTools(sessions, backend),
         code_block=CodeBlockTools(sessions, backend),
         imports=ImportTools(sessions, backend),
+        exports=ExportTools(sessions, backend),
         task=TaskContextTools(sessions, backend),
         files=FileTools(sessions, backend),
         builder_feedback=FeedbackTools(backend, mcp_side="App Builder MCP"),

package/src/qingflow_mcp/cli/formatters.py

@@ -1,17 +1,26 @@
 from __future__ import annotations
 
 import json
+import textwrap
 from typing import Any, TextIO
 
 
 def emit_text_result(result: dict[str, Any], *, hint: str, stream: TextIO) -> None:
-    formatter = _FORMATTERS.get(hint, _format_generic)
-    text = formatter(result)
+    text = _format_cancelled_result(result)
+    if text is None:
+        formatter = _FORMATTERS.get(hint, _format_generic)
+        text = formatter(result)
     stream.write(text)
     if not text.endswith("\n"):
         stream.write("\n")
 
 
+def _format_cancelled_result(result: dict[str, Any]) -> str | None:
+    if str(result.get("status") or "").lower() != "cancelled":
+        return None
+    return str(result.get("message") or "已取消") + "\n"
+
+
 def _format_generic(result: dict[str, Any]) -> str:
     lines: list[str] = []
     title = _first_present(result, "status", "message")
@@ -106,6 +115,21 @@ def _format_workspace_get(result: dict[str, Any]) -> str:
     return "\n".join(lines) + "\n"
 
 
+def _format_workspace_select(result: dict[str, Any]) -> str:
+    status = str(result.get("status") or "").lower()
+    if status == "cancelled":
+        return str(result.get("message") or "已取消") + "\n"
+
+    workspace = result.get("workspace") if isinstance(result.get("workspace"), dict) else {}
+    workspace_name = workspace.get("workspaceName") or workspace.get("wsName") or result.get("selected", {}).get("workspace_name") if isinstance(result.get("selected"), dict) else None
+    lines = [
+        f"已切换到: {workspace_name or '-'} ({workspace.get('wsId') or result.get('ws_id') or '-'})",
+        f"QF Version: {result.get('qf_version') or workspace.get('systemVersion') or '-'}",
+    ]
+    _append_warnings(lines, result.get("warnings"))
+    return "\n".join(lines) + "\n"
+
+
 def _format_app_items(result: dict[str, Any]) -> str:
     items = result.get("items")
     if not isinstance(items, list):
@@ -159,7 +183,17 @@ def _format_app_get(result: dict[str, Any]) -> str:
 def _format_record_list(result: dict[str, Any]) -> str:
     data = result.get("data") if isinstance(result.get("data"), dict) else {}
     items = data.get("items") if isinstance(data.get("items"), list) else []
-    lines = [f"Returned Records: {len(items)}"]
+    lines: list[str] = []
+    lookup = result.get("lookup") if isinstance(result.get("lookup"), dict) else {}
+    if lookup:
+        lines.append("Lookup:")
+        lines.append(f"- query: {lookup.get('query')}")
+        lines.append(f"- confidence: {lookup.get('confidence')}")
+        lines.append(f"- next_action: {lookup.get('next_action')}")
+        lines.append(f"- total_count: {lookup.get('total_count')}")
+        lines.append(f"- returned_count: {lookup.get('returned_count')}")
+        lines.append(f"- truncated: {lookup.get('truncated')}")
+    lines.append(f"Returned Records: {len(items)}")
     for item in items[:10]:
         if isinstance(item, dict):
             lines.append(json.dumps(item, ensure_ascii=False))
@@ -170,6 +204,94 @@ def _format_record_list(result: dict[str, Any]) -> str:
     return "\n".join(lines) + "\n"
 
 
+def _format_record_access(result: dict[str, Any]) -> str:
+    status = result.get("status") or "-"
+    lines = [
+        f"Status: {status}",
+        f"Rows: {result.get('row_count')}",
+        f"Complete: {result.get('complete')}",
+        f"Safe for final conclusion: {result.get('safe_for_final_conclusion')}",
+    ]
+    if result.get("local_dir"):
+        lines.append(f"Local dir: {result.get('local_dir')}")
+    files = result.get("files") if isinstance(result.get("files"), list) else []
+    if files:
+        lines.append("Files:")
+        for item in files:
+            if isinstance(item, dict):
+                lines.append(f"- part {item.get('part')}: {item.get('local_path')} ({item.get('row_count')} rows)")
+    scope = result.get("scope") if isinstance(result.get("scope"), dict) else {}
+    if status == "needs_scope" and scope:
+        lines.append("Scope required:")
+        lines.append(f"- reported_total: {scope.get('reported_total')}")
+        lines.append(f"- estimated_pages: {scope.get('estimated_pages')}")
+        suggested = scope.get("suggested_time_fields") if isinstance(scope.get("suggested_time_fields"), list) else []
+        if suggested:
+            names = ", ".join(str(item.get("title") or item.get("field_id")) for item in suggested if isinstance(item, dict))
+            lines.append(f"- suggested_time_fields: {names}")
+    _append_warnings(lines, result.get("warnings"))
+    _append_verification(lines, result.get("verification"))
+    return "\n".join(lines) + "\n"
+
+
+def _format_record_get(result: dict[str, Any]) -> str:
+    record = result.get("record") if isinstance(result.get("record"), dict) else {}
+    app = result.get("app") if isinstance(result.get("app"), dict) else {}
+    view = result.get("view") if isinstance(result.get("view"), dict) else {}
+    fields = result.get("fields") if isinstance(result.get("fields"), list) else []
+    data_logs = result.get("data_logs") if isinstance(result.get("data_logs"), dict) else {}
+    workflow_logs = result.get("workflow_logs") if isinstance(result.get("workflow_logs"), dict) else {}
+    media_assets = result.get("media_assets") if isinstance(result.get("media_assets"), dict) else {}
+    media_items = media_assets.get("items") if isinstance(media_assets.get("items"), list) else []
+    downloaded_media = [item for item in media_items if isinstance(item, dict) and item.get("access_status") == "downloaded"]
+    failed_media = [item for item in media_items if isinstance(item, dict) and item.get("access_status") != "downloaded"]
+    file_assets = result.get("file_assets") if isinstance(result.get("file_assets"), dict) else {}
+    file_items = file_assets.get("items") if isinstance(file_assets.get("items"), list) else []
+    downloaded_files = [item for item in file_items if isinstance(item, dict) and item.get("access_status") == "downloaded"]
+    failed_files = [item for item in file_items if isinstance(item, dict) and item.get("access_status") != "downloaded"]
+    extracted_files = [
+        item
+        for item in downloaded_files
+        if isinstance(item.get("extraction"), dict) and item["extraction"].get("status") == "ok"
+    ]
+    associated_resources = result.get("associated_resources") if isinstance(result.get("associated_resources"), list) else []
+    unavailable_context = result.get("unavailable_context") if isinstance(result.get("unavailable_context"), list) else []
+    lines = [
+        f"Status: {result.get('status') or '-'}",
+        f"App: {app.get('app_name') or app.get('app_key') or '-'} ({app.get('app_key') or '-'})",
+        f"View: {view.get('name') or view.get('view_id') or '-'}",
+        f"Record: {record.get('title') or '-'} ({record.get('record_id') or '-'})",
+        f"Fields: {len(fields)}",
+        f"Data logs: {data_logs.get('status') or '-'} / loaded={data_logs.get('items_loaded')}",
+        f"Workflow logs: {workflow_logs.get('status') or '-'} / loaded={workflow_logs.get('items_loaded')}",
+        f"Media assets: {media_assets.get('status') or '-'} / downloaded={len(downloaded_media)} / failed={len(failed_media)}",
+        f"File assets: {file_assets.get('status') or '-'} / downloaded={len(downloaded_files)} / extracted={len(extracted_files)} / failed={len(failed_files)}",
+        f"Associated resources: {len(associated_resources)}",
+        f"Unavailable contexts: {len(unavailable_context)}",
+    ]
+    if media_assets.get("local_dir"):
+        lines.append(f"Media dir: {media_assets.get('local_dir')}")
+    if file_assets.get("local_dir"):
+        lines.append(f"File dir: {file_assets.get('local_dir')}")
+    if failed_media:
+        failure_counts: dict[str, int] = {}
+        for item in failed_media:
+            key = f"{item.get('access_status') or 'unknown'} via {item.get('download_strategy') or 'unknown'}"
+            failure_counts[key] = failure_counts.get(key, 0) + 1
+        lines.append("Media failures: " + ", ".join(f"{key}={count}" for key, count in sorted(failure_counts.items())))
+    if failed_files:
+        failure_counts = {}
+        for item in failed_files:
+            key = f"{item.get('access_status') or 'unknown'} via {item.get('download_strategy') or 'unknown'}"
+            failure_counts[key] = failure_counts.get(key, 0) + 1
+        lines.append("File failures: " + ", ".join(f"{key}={count}" for key, count in sorted(failure_counts.items())))
+    summary = result.get("summary") if isinstance(result.get("summary"), dict) else {}
+    if summary.get("text"):
+        lines.append(f"Summary: {summary.get('text')}")
+    _append_warnings(lines, result.get("warnings"))
+    return "\n".join(lines) + "\n"
+
+
 def _format_task_list(result: dict[str, Any]) -> str:
     data = result.get("data") if isinstance(result.get("data"), dict) else {}
     items = data.get("items") if isinstance(data.get("items"), list) else []
@@ -214,15 +336,22 @@ def _format_task_get(result: dict[str, Any]) -> str:
             f"App: {task.get('app_name') or '-'}",
             f"Initiator: {initiator_label}",
             f"Apply Status: {record_summary.get('apply_status')}",
+            f"Apply Number: {record_summary.get('custom_apply_num') or record_summary.get('apply_num') or '-'}",
+            f"Apply Time: {record_summary.get('apply_time') or '-'}",
             f"Available Actions: {', '.join(str(item) for item in available_actions) or '-'}",
             f"Editable Fields: {len(editable_fields)}",
         ]
     )
+    all_fields = record_summary.get("all_fields") if isinstance(record_summary.get("all_fields"), dict) else {}
     core_fields = record_summary.get("core_fields") if isinstance(record_summary.get("core_fields"), dict) else {}
-    if core_fields:
+    if all_fields:
+        lines.append("Fields:")
+        for key, value in all_fields.items():
+            lines.extend(_format_field_line(key, value))
+    elif core_fields:
         lines.append("Core Fields:")
         for key, value in list(core_fields.items())[:12]:
-            lines.append(f"- {key}: {value}")
+            lines.extend(_format_field_line(key, value))
     if editable_fields:
         lines.append("Editable Fields:")
         for item in editable_fields[:10]:
@@ -273,6 +402,30 @@ def _format_task_action(result: dict[str, Any]) -> str:
     return _task_action_success_label(action) + "\n"
 
 
+def _format_task_workbench(result: dict[str, Any]) -> str:
+    message = str(result.get("message") or "").strip()
+    if message:
+        return message + "\n"
+    return ""
+
+
+def _format_field_line(key: Any, value: Any) -> list[str]:
+    if isinstance(value, list):
+        text = " / ".join(str(item) for item in value if item not in (None, ""))
+    else:
+        text = str(value if value not in (None, "") else "-")
+    wrapped = textwrap.wrap(
+        text,
+        width=120,
+        initial_indent=f"- {key}: ",
+        subsequent_indent="  ",
+        replace_whitespace=False,
+        drop_whitespace=False,
+        break_long_words=True,
+    )
+    return wrapped or [f"- {key}: -"]
+
+
 def _format_task_associated_report_detail(result: dict[str, Any]) -> str:
     data = result.get("data") if isinstance(result.get("data"), dict) else {}
     selection = data.get("selection") if isinstance(data.get("selection"), dict) else {}
@@ -352,11 +505,85 @@ def _format_import_status(result: dict[str, Any]) -> str:
         f"Failed Rows: {result.get('failed') or 0}",
         f"Progress: {result.get('progress') or '-'}",
     ]
+    if result.get("process_status") not in (None, ""):
+        lines.append(f"Process Status: {result.get('process_status')}")
+    error_file_urls = result.get("error_file_urls") if isinstance(result.get("error_file_urls"), list) else []
+    if error_file_urls:
+        lines.append("Error Files:")
+        for url in error_file_urls:
+            lines.append(f"- {url}")
+    _append_warnings(lines, result.get("warnings"))
+    _append_verification(lines, result.get("verification"))
+    return "\n".join(lines) + "\n"
+
+
+def _format_export_common(result: dict[str, Any], *, title: str | None = None) -> str:
+    lines: list[str] = []
+    if title:
+        lines.append(title)
+    lines.extend(
+        [
+            f"Status: {result.get('status') or '-'}",
+            f"Export Handle: {result.get('export_handle') or '-'}",
+            f"App Key: {result.get('app_key') or '-'}",
+            f"View ID: {result.get('view_id') or '-'}",
+            f"Process Status: {result.get('process_status') or '-'}",
+            f"Rows: {result.get('num') if result.get('num') is not None else '-'}",
+        ]
+    )
+    row_scope = result.get("row_scope")
+    if row_scope not in (None, ""):
+        lines.append(f"Row Scope: {row_scope}")
+    selected_record_count = result.get("selected_record_count")
+    if selected_record_count not in (None, ""):
+        lines.append(f"Selected Rows: {selected_record_count}")
+    field_scope = result.get("field_scope")
+    if field_scope not in (None, ""):
+        lines.append(f"Field Scope: {field_scope}")
+    selected_field_count = result.get("selected_field_count")
+    if selected_field_count not in (None, ""):
+        lines.append(f"Selected Fields: {selected_field_count}")
+    include_workflow_log = result.get("include_workflow_log")
+    if include_workflow_log not in (None, ""):
+        lines.append(f"Include Workflow Log: {include_workflow_log}")
+    file_names = result.get("file_names") if isinstance(result.get("file_names"), list) else []
+    file_urls = result.get("file_urls") if isinstance(result.get("file_urls"), list) else []
+    if file_names or file_urls:
+        lines.append("Remote Files:")
+        max_items = max(len(file_names), len(file_urls))
+        for index in range(max_items):
+            name = file_names[index] if index < len(file_names) else "-"
+            url = file_urls[index] if index < len(file_urls) else "-"
+            lines.append(f"- {name}: {url}")
+    downloaded_files = result.get("downloaded_files") if isinstance(result.get("downloaded_files"), list) else []
+    if downloaded_files:
+        lines.append("Downloaded Files:")
+        for item in downloaded_files:
+            if isinstance(item, dict):
+                lines.append(f"- {item.get('file_name') or '-'}: {item.get('path') or '-'}")
+            else:
+                lines.append(f"- {item}")
     _append_warnings(lines, result.get("warnings"))
     _append_verification(lines, result.get("verification"))
     return "\n".join(lines) + "\n"
 
 
+def _format_export_start(result: dict[str, Any]) -> str:
+    return _format_export_common(result, title="Export Accepted")
+
+
+def _format_export_status(result: dict[str, Any]) -> str:
+    return _format_export_common(result, title="Export Status")
+
+
+def _format_export_get(result: dict[str, Any]) -> str:
+    return _format_export_common(result, title="Export Result")
+
+
+def _format_export_direct(result: dict[str, Any]) -> str:
+    return _format_export_common(result, title="Export Direct")
+
+
 def _format_builder_summary(result: dict[str, Any]) -> str:
     lines = []
     if "status" in result:
@@ -559,15 +786,23 @@ _FORMATTERS = {
     "auth_whoami": _format_whoami,
     "workspace_list": _format_workspace_list,
     "workspace_get": _format_workspace_get,
+    "workspace_select": _format_workspace_select,
     "app_list": _format_app_items,
     "app_search": _format_app_items,
     "app_get": _format_app_get,
     "record_list": _format_record_list,
+    "record_access": _format_record_access,
+    "record_get": _format_record_get,
     "task_list": _format_task_list,
+    "task_workbench": _format_task_workbench,
     "task_get": _format_task_get,
     "task_action_execute": _format_task_action,
     "task_associated_report_detail_get": _format_task_associated_report_detail,
     "import_verify": _format_import_verify,
     "import_status": _format_import_status,
+    "export_start": _format_export_start,
+    "export_status": _format_export_status,
+    "export_get": _format_export_get,
+    "export_direct": _format_export_direct,
     "builder_summary": _format_builder_summary,
 }

package/src/qingflow_mcp/cli/interaction.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Generic, TypeVar
+
+from .terminal_ui import SelectionOption, select_option
+
+
+T = TypeVar("T")
+
+
+@dataclass(slots=True)
+class InteractiveSelectionResult(Generic[T]):
+    status: str
+    value: T | None = None
+    message: str | None = None
+
+
+def cancelled_result(message: str = "已取消") -> dict[str, str]:
+    return {"status": "cancelled", "message": message}
+
+
+def resolve_interactive_selection(
+    args: object,
+    *,
+    title: str,
+    unavailable_message: str,
+    empty_message: str,
+    load_options: Callable[[], list[SelectionOption[T]]],
+) -> InteractiveSelectionResult[T]:
+    input_stream = getattr(args, "_stdin", None)
+    output_stream = getattr(args, "_stderr_stream", None)
+    if input_stream is None or output_stream is None:
+        return InteractiveSelectionResult(status="unavailable", message=unavailable_message)
+    if not bool(getattr(input_stream, "isatty", lambda: False)()):
+        return InteractiveSelectionResult(status="unavailable", message=unavailable_message)
+
+    options = list(load_options())
+    if not options:
+        return InteractiveSelectionResult(status="empty", message=empty_message)
+
+    value = select_option(
+        title=title,
+        options=options,
+        input_stream=input_stream,
+        output_stream=output_stream,
+    )
+    if value is None:
+        return InteractiveSelectionResult(status="cancelled", message="已取消")
+    return InteractiveSelectionResult(status="selected", value=value)
+
+
+def resolve_interactive_text_input(
+    args: object,
+    *,
+    prompt: str,
+    unavailable_message: str,
+) -> InteractiveSelectionResult[str]:
+    input_stream = getattr(args, "_stdin", None)
+    output_stream = getattr(args, "_stderr_stream", None)
+    if input_stream is None or output_stream is None:
+        return InteractiveSelectionResult(status="unavailable", message=unavailable_message)
+    if not bool(getattr(input_stream, "isatty", lambda: False)()):
+        return InteractiveSelectionResult(status="unavailable", message=unavailable_message)
+
+    output_stream.write(prompt)
+    output_stream.flush()
+    line = input_stream.readline()
+    text = str(line or "").strip()
+    if not text:
+        return InteractiveSelectionResult(status="cancelled", message="已取消")
+    return InteractiveSelectionResult(status="selected", value=text)

package/src/qingflow_mcp/cli/main.py

@@ -44,6 +44,9 @@ def run(
         args = parser.parse_args(normalized_argv)
     except SystemExit as exc:
         return int(exc.code or 0)
+    setattr(args, "_stdin", sys.stdin)
+    setattr(args, "_stdout_stream", out)
+    setattr(args, "_stderr_stream", err)
     handler = getattr(args, "handler", None)
     if handler is None:
         parser.print_help(out)
@@ -53,6 +56,8 @@ def run(
         if not bool(args.json):
             _emit_cli_effective_context_notice(args, context, stream=err)
         result = handler(args, context)
+    except SystemExit as exc:
+        return int(exc.code or 0)
     except RuntimeError as exc:
         payload = trim_error_response(_parse_error_payload(exc))
         return _emit_error(payload, json_mode=bool(args.json), stdout=out, stderr=err)