@josephyan/qingflow-cli 0.2.0-beta.55

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

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import argparse
+
+from ..context import CliContext
+from .common import load_object_arg
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser("task", help="待办与流程上下文")
+    task_subparsers = parser.add_subparsers(dest="task_command", required=True)
+
+    list_parser = task_subparsers.add_parser("list", help="列出待办")
+    list_parser.add_argument("--task-box", default="todo")
+    list_parser.add_argument("--flow-status", default="all")
+    list_parser.add_argument("--app-key")
+    list_parser.add_argument("--workflow-node-id", type=int)
+    list_parser.add_argument("--query")
+    list_parser.add_argument("--page", type=int, default=1)
+    list_parser.add_argument("--page-size", type=int, default=20)
+    list_parser.set_defaults(handler=_handle_list, format_hint="task_list")
+
+    get = task_subparsers.add_parser("get", help="读取待办详情")
+    get.add_argument("--app-key", required=True)
+    get.add_argument("--record-id", required=True, type=int)
+    get.add_argument("--workflow-node-id", required=True, type=int)
+    get.add_argument("--include-candidates", action=argparse.BooleanOptionalAction, default=True)
+    get.add_argument("--include-associated-reports", action=argparse.BooleanOptionalAction, default=True)
+    get.set_defaults(handler=_handle_get, format_hint="")
+
+    action = task_subparsers.add_parser("action", help="执行待办动作")
+    action.add_argument("--app-key", required=True)
+    action.add_argument("--record-id", required=True, type=int)
+    action.add_argument("--workflow-node-id", required=True, type=int)
+    action.add_argument("--action", required=True)
+    action.add_argument("--payload-file")
+    action.set_defaults(handler=_handle_action, format_hint="")
+
+    log = task_subparsers.add_parser("log", help="读取流程日志")
+    log.add_argument("--app-key", required=True)
+    log.add_argument("--record-id", required=True, type=int)
+    log.add_argument("--workflow-node-id", required=True, type=int)
+    log.set_defaults(handler=_handle_log, format_hint="")
+
+
+def _handle_list(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.task.task_list(
+        profile=args.profile,
+        task_box=args.task_box,
+        flow_status=args.flow_status,
+        app_key=args.app_key,
+        workflow_node_id=args.workflow_node_id,
+        query=args.query,
+        page=args.page,
+        page_size=args.page_size,
+    )
+
+
+def _handle_get(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.task.task_get(
+        profile=args.profile,
+        app_key=args.app_key,
+        record_id=args.record_id,
+        workflow_node_id=args.workflow_node_id,
+        include_candidates=bool(args.include_candidates),
+        include_associated_reports=bool(args.include_associated_reports),
+    )
+
+
+def _handle_action(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.task.task_action_execute(
+        profile=args.profile,
+        app_key=args.app_key,
+        record_id=args.record_id,
+        workflow_node_id=args.workflow_node_id,
+        action=args.action,
+        payload=load_object_arg(args.payload_file, option_name="--payload-file") or {},
+    )
+
+
+def _handle_log(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.task.task_workflow_log_get(
+        profile=args.profile,
+        app_key=args.app_key,
+        record_id=args.record_id,
+        workflow_node_id=args.workflow_node_id,
+    )

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

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import argparse
+
+from ..context import CliContext
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser("workspace", help="工作区")
+    workspace_subparsers = parser.add_subparsers(dest="workspace_command", required=True)
+
+    list_parser = workspace_subparsers.add_parser("list", help="列出工作区")
+    list_parser.add_argument("--page", type=int, default=1)
+    list_parser.add_argument("--page-size", type=int, default=20)
+    list_parser.add_argument("--include-external", action="store_true")
+    list_parser.set_defaults(handler=_handle_list, format_hint="workspace_list")
+
+    select = workspace_subparsers.add_parser("select", help="切换工作区")
+    select.add_argument("--ws-id", type=int, required=True)
+    select.set_defaults(handler=_handle_select, format_hint="")
+
+
+def _handle_list(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.workspace.workspace_list(
+        profile=args.profile,
+        page_num=args.page,
+        page_size=args.page_size,
+        include_external=bool(args.include_external),
+    )
+
+
+def _handle_select(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.workspace.workspace_select(profile=args.profile, ws_id=args.ws_id)

package/src/qingflow_mcp/cli/context.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..backend_client import BackendClient
+from ..session_store import SessionStore
+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.import_tools import ImportTools
+from ..tools.record_tools import RecordTools
+from ..tools.task_context_tools import TaskContextTools
+from ..tools.workspace_tools import WorkspaceTools
+
+
+@dataclass(slots=True)
+class CliContext:
+    sessions: SessionStore
+    backend: BackendClient
+    auth: AuthTools
+    workspace: WorkspaceTools
+    app: AppTools
+    record: RecordTools
+    code_block: CodeBlockTools
+    imports: ImportTools
+    task: TaskContextTools
+    builder: AiBuilderTools
+
+    def close(self) -> None:
+        self.backend.close()
+
+
+def build_cli_context() -> CliContext:
+    sessions = SessionStore()
+    backend = BackendClient()
+    return CliContext(
+        sessions=sessions,
+        backend=backend,
+        auth=AuthTools(sessions, backend),
+        workspace=WorkspaceTools(sessions, backend),
+        app=AppTools(sessions, backend),
+        record=RecordTools(sessions, backend),
+        code_block=CodeBlockTools(sessions, backend),
+        imports=ImportTools(sessions, backend),
+        task=TaskContextTools(sessions, backend),
+        builder=AiBuilderTools(sessions, backend),
+    )

package/src/qingflow_mcp/cli/formatters.py

@@ -0,0 +1,269 @@
+from __future__ import annotations
+
+import json
+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)
+    stream.write(text)
+    if not text.endswith("\n"):
+        stream.write("\n")
+
+
+def _format_generic(result: dict[str, Any]) -> str:
+    lines: list[str] = []
+    title = _first_present(result, "status", "message")
+    if title:
+        lines.append(str(title))
+    data = result.get("data")
+    if isinstance(data, dict):
+        scalar_lines = _dict_scalar_lines(data)
+        if scalar_lines:
+            lines.extend(scalar_lines)
+    elif result:
+        scalar_lines = _dict_scalar_lines(result)
+        if scalar_lines:
+            lines.extend(scalar_lines)
+    if not lines:
+        lines.append(json.dumps(result, ensure_ascii=False, indent=2))
+    _append_warnings(lines, result.get("warnings"))
+    _append_verification(lines, result.get("verification"))
+    return "\n".join(lines) + "\n"
+
+
+def _format_whoami(result: dict[str, Any]) -> str:
+    lines = [
+        f"Profile: {result.get('profile')}",
+        f"User: {result.get('nick_name') or '-'} ({result.get('email') or '-'})",
+        f"UID: {result.get('uid')}",
+        f"Workspace: {result.get('selected_ws_name') or '-'} ({result.get('selected_ws_id') or '-'})",
+        f"Base URL: {result.get('base_url')}",
+    ]
+    return "\n".join(lines) + "\n"
+
+
+def _format_workspace_list(result: dict[str, Any]) -> str:
+    page = result.get("page") if isinstance(result.get("page"), dict) else {}
+    items = page.get("list") if isinstance(page.get("list"), list) else []
+    rows = []
+    for item in items:
+        if not isinstance(item, dict):
+            continue
+        rows.append(
+            [
+                str(item.get("wsId") or ""),
+                str(item.get("workspaceName") or item.get("wsName") or ""),
+                str(item.get("remark") or ""),
+            ]
+        )
+    return _render_titled_table("Workspaces", ["ws_id", "name", "remark"], rows)
+
+
+def _format_app_items(result: dict[str, Any]) -> str:
+    items = result.get("items")
+    if not isinstance(items, list):
+        items = result.get("apps")
+    rows = []
+    for item in items or []:
+        if not isinstance(item, dict):
+            continue
+        rows.append(
+            [
+                str(item.get("app_key") or item.get("appKey") or ""),
+                str(item.get("app_name") or item.get("name") or item.get("title") or ""),
+                str(item.get("package_name") or item.get("tag_name") or ""),
+            ]
+        )
+    return _render_titled_table("Apps", ["app_key", "app_name", "package"], rows)
+
+
+def _format_app_get(result: dict[str, Any]) -> str:
+    data = result.get("data") if isinstance(result.get("data"), dict) else {}
+    lines = [
+        f"App: {data.get('app_name') or '-'}",
+        f"App Key: {data.get('app_key') or '-'}",
+        f"Can Create: {data.get('can_create')}",
+    ]
+    import_capability = data.get("import_capability")
+    if isinstance(import_capability, dict):
+        lines.append(
+            "Import Capability: "
+            f"{import_capability.get('auth_source') or 'unknown'} / "
+            f"can_import={import_capability.get('can_import')}"
+        )
+    views = data.get("accessible_views") if isinstance(data.get("accessible_views"), list) else []
+    lines.append(f"Accessible Views: {len(views)}")
+    for item in views[:10]:
+        if isinstance(item, dict):
+            lines.append(f"- {item.get('view_id')}: {item.get('name')}")
+    _append_warnings(lines, result.get("warnings"))
+    return "\n".join(lines) + "\n"
+
+
+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)}"]
+    for item in items[:10]:
+        if isinstance(item, dict):
+            lines.append(json.dumps(item, ensure_ascii=False))
+    if len(items) > 10:
+        lines.append(f"... {len(items) - 10} more")
+    _append_warnings(lines, result.get("warnings"))
+    _append_verification(lines, result.get("verification"))
+    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 []
+    rows = []
+    for item in items:
+        if not isinstance(item, dict):
+            continue
+        rows.append(
+            [
+                str(item.get("app_key") or ""),
+                str(item.get("record_id") or ""),
+                str(item.get("workflow_node_id") or ""),
+                str(item.get("title") or item.get("task_name") or ""),
+            ]
+        )
+    output = _render_titled_table("Tasks", ["app_key", "record_id", "node_id", "title"], rows)
+    lines = output.rstrip("\n").split("\n")
+    _append_warnings(lines, result.get("warnings"))
+    return "\n".join(lines) + "\n"
+
+
+def _format_import_verify(result: dict[str, Any]) -> str:
+    lines = [
+        f"App Key: {result.get('app_key') or '-'}",
+        f"File: {result.get('file_name') or result.get('file_path') or '-'}",
+        f"Can Import: {result.get('can_import')}",
+        f"Apply Rows: {result.get('apply_rows')}",
+        f"Verification ID: {result.get('verification_id') or '-'}",
+    ]
+    issues = result.get("issues") if isinstance(result.get("issues"), list) else []
+    if issues:
+        lines.append("Issues:")
+        for issue in issues:
+            if isinstance(issue, dict):
+                lines.append(f"- {issue.get('code') or 'ISSUE'}: {issue.get('message') or issue}")
+            else:
+                lines.append(f"- {issue}")
+    _append_warnings(lines, result.get("warnings"))
+    _append_verification(lines, result.get("verification"))
+    return "\n".join(lines) + "\n"
+
+
+def _format_import_status(result: dict[str, Any]) -> str:
+    lines = [
+        f"Status: {result.get('status') or '-'}",
+        f"Import ID: {result.get('import_id') or '-'}",
+        f"Process ID: {result.get('process_id_str') or '-'}",
+        f"Success Rows: {result.get('success_rows') or 0}",
+        f"Failed Rows: {result.get('failed_rows') or 0}",
+        f"Progress: {result.get('progress') or '-'}",
+    ]
+    _append_warnings(lines, result.get("warnings"))
+    _append_verification(lines, result.get("verification"))
+    return "\n".join(lines) + "\n"
+
+
+def _format_builder_summary(result: dict[str, Any]) -> str:
+    lines = []
+    if "status" in result:
+        lines.append(f"Status: {result.get('status')}")
+    if "app_key" in result:
+        lines.append(f"App Key: {result.get('app_key')}")
+    if "dash_key" in result:
+        lines.append(f"Dash Key: {result.get('dash_key')}")
+    if "verified" in result:
+        lines.append(f"Verified: {result.get('verified')}")
+    data = result.get("data")
+    if isinstance(data, dict):
+        scalar_lines = _dict_scalar_lines(data)
+        lines.extend(scalar_lines[:8])
+    _append_warnings(lines, result.get("warnings"))
+    _append_verification(lines, result.get("verification"))
+    if not lines:
+        return _format_generic(result)
+    return "\n".join(lines) + "\n"
+
+
+def emit_json_result(result: dict[str, Any], *, stream: TextIO) -> None:
+    json.dump(result, stream, ensure_ascii=False, indent=2)
+    stream.write("\n")
+
+
+def _render_titled_table(title: str, headers: list[str], rows: list[list[str]]) -> str:
+    lines = [title]
+    if not rows:
+        lines.append("(empty)")
+        return "\n".join(lines) + "\n"
+    widths = [len(header) for header in headers]
+    for row in rows:
+        for index, cell in enumerate(row):
+            widths[index] = max(widths[index], len(cell))
+    header_line = "  ".join(header.ljust(widths[index]) for index, header in enumerate(headers))
+    lines.append(header_line)
+    lines.append("  ".join("-" * width for width in widths))
+    for row in rows:
+        lines.append("  ".join(cell.ljust(widths[index]) for index, cell in enumerate(row)))
+    return "\n".join(lines) + "\n"
+
+
+def _dict_scalar_lines(payload: dict[str, Any]) -> list[str]:
+    lines: list[str] = []
+    for key, value in payload.items():
+        if isinstance(value, (str, int, float, bool)) or value is None:
+            lines.append(f"{key}: {value}")
+    return lines
+
+
+def _append_warnings(lines: list[str], warnings: Any) -> None:
+    if not isinstance(warnings, list) or not warnings:
+        return
+    lines.append("Warnings:")
+    for warning in warnings:
+        if isinstance(warning, dict):
+            code = warning.get("code")
+            message = warning.get("message")
+            if code or message:
+                lines.append(f"- {code or 'WARNING'}: {message or ''}".rstrip())
+            else:
+                lines.append(f"- {json.dumps(warning, ensure_ascii=False)}")
+        else:
+            lines.append(f"- {warning}")
+
+
+def _append_verification(lines: list[str], verification: Any) -> None:
+    if not isinstance(verification, dict) or not verification:
+        return
+    lines.append("Verification:")
+    for key, value in verification.items():
+        if isinstance(value, (str, int, float, bool)) or value is None:
+            lines.append(f"- {key}: {value}")
+
+
+def _first_present(payload: dict[str, Any], *keys: str) -> Any:
+    for key in keys:
+        if key in payload and payload.get(key) is not None:
+            return payload.get(key)
+    return None
+
+
+_FORMATTERS = {
+    "auth_whoami": _format_whoami,
+    "workspace_list": _format_workspace_list,
+    "app_list": _format_app_items,
+    "app_search": _format_app_items,
+    "app_get": _format_app_get,
+    "record_list": _format_record_list,
+    "task_list": _format_task_list,
+    "import_verify": _format_import_verify,
+    "import_status": _format_import_status,
+    "builder_summary": _format_builder_summary,
+}

package/src/qingflow_mcp/cli/json_io.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from ..errors import QingflowApiError
+
+
+def load_json_value(path: str, *, option_name: str) -> Any:
+    if not path:
+        raise QingflowApiError.config_error(f"{option_name} is required")
+    if path == "-":
+        raw = sys.stdin.read()
+    else:
+        try:
+            raw = Path(path).expanduser().read_text(encoding="utf-8")
+        except OSError as exc:
+            raise QingflowApiError.config_error(f"failed to read {option_name} from '{path}': {exc}") from exc
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise QingflowApiError.config_error(f"{option_name} must contain valid JSON: {exc}") from exc
+
+
+def load_json_object(path: str, *, option_name: str) -> dict[str, Any]:
+    payload = load_json_value(path, option_name=option_name)
+    if not isinstance(payload, dict):
+        raise QingflowApiError.config_error(f"{option_name} must be a JSON object")
+    return payload
+
+
+def load_json_list(path: str, *, option_name: str) -> list[Any]:
+    payload = load_json_value(path, option_name=option_name)
+    if not isinstance(payload, list):
+        raise QingflowApiError.config_error(f"{option_name} must be a JSON array")
+    return payload
+
+
+def load_optional_json_object(path: str | None, *, option_name: str) -> dict[str, Any] | None:
+    if not path:
+        return None
+    return load_json_object(path, option_name=option_name)
+
+
+def load_optional_json_list(path: str | None, *, option_name: str) -> list[Any]:
+    if not path:
+        return []
+    return load_json_list(path, option_name=option_name)

package/src/qingflow_mcp/cli/main.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any, Callable, TextIO
+
+from ..errors import QingflowApiError
+from .context import CliContext, build_cli_context
+from .formatters import emit_json_result, emit_text_result
+from .commands import register_all_commands
+
+
+Handler = Callable[[argparse.Namespace, CliContext], dict[str, Any]]
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="qingflow", description="Qingflow CLI")
+    parser.add_argument("--profile", default="default", help="会话 profile，默认 default")
+    parser.add_argument("--json", action="store_true", help="输出原始 JSON")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    register_all_commands(subparsers)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    raise SystemExit(run(argv))
+
+
+def run(
+    argv: list[str] | None = None,
+    *,
+    context_factory: Callable[[], CliContext] = build_cli_context,
+    stdout: TextIO | None = None,
+    stderr: TextIO | None = None,
+) -> int:
+    out = stdout or sys.stdout
+    err = stderr or sys.stderr
+    parser = build_parser()
+    normalized_argv = _normalize_global_args(list(argv) if argv is not None else sys.argv[1:])
+    try:
+        args = parser.parse_args(normalized_argv)
+    except SystemExit as exc:
+        return int(exc.code or 0)
+    handler = getattr(args, "handler", None)
+    if handler is None:
+        parser.print_help(out)
+        return 2
+    context = context_factory()
+    try:
+        result = handler(args, context)
+    except RuntimeError as exc:
+        payload = _parse_error_payload(exc)
+        return _emit_error(payload, json_mode=bool(args.json), stdout=out, stderr=err)
+    except QingflowApiError as exc:
+        payload = exc.to_dict()
+        return _emit_error(payload, json_mode=bool(args.json), stdout=out, stderr=err)
+    finally:
+        context.close()
+
+    exit_code = _result_exit_code(result)
+    stream = out if bool(args.json) or exit_code == 0 else err
+    if bool(args.json):
+        emit_json_result(result, stream=stream)
+    else:
+        emit_text_result(result, hint=getattr(args, "format_hint", ""), stream=stream)
+    return exit_code
+
+
+def _normalize_global_args(argv: list[str]) -> list[str]:
+    global_args: list[str] = []
+    remaining: list[str] = []
+    index = 0
+    while index < len(argv):
+        token = argv[index]
+        if token == "--json":
+            global_args.append(token)
+            index += 1
+            continue
+        if token == "--profile":
+            global_args.append(token)
+            if index + 1 >= len(argv):
+                global_args.append("")
+                break
+            global_args.append(argv[index + 1])
+            index += 2
+            continue
+        if token.startswith("--profile="):
+            global_args.append(token)
+            index += 1
+            continue
+        remaining.append(token)
+        index += 1
+    return global_args + remaining
+
+
+def _parse_error_payload(exc: RuntimeError) -> dict[str, Any]:
+    raw = str(exc)
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError:
+        return {"category": "runtime", "message": raw}
+    return payload if isinstance(payload, dict) else {"category": "runtime", "message": raw}
+
+
+def _emit_error(payload: dict[str, Any], *, json_mode: bool, stdout: TextIO, stderr: TextIO) -> int:
+    exit_code = _error_exit_code(payload)
+    if json_mode:
+        emit_json_result(payload, stream=stdout)
+        return exit_code
+    lines = [
+        f"Category: {payload.get('category') or 'error'}",
+        f"Message: {payload.get('message') or 'Unknown error'}",
+    ]
+    if payload.get("backend_code") is not None:
+        lines.append(f"Backend Code: {payload.get('backend_code')}")
+    if payload.get("request_id"):
+        lines.append(f"Request ID: {payload.get('request_id')}")
+    details = payload.get("details")
+    if isinstance(details, dict):
+        for key, value in details.items():
+            if isinstance(value, (str, int, float, bool)) or value is None:
+                lines.append(f"{key}: {value}")
+    stderr.write("\n".join(lines) + "\n")
+    return exit_code
+
+
+def _error_exit_code(payload: dict[str, Any]) -> int:
+    category = str(payload.get("category") or "").lower()
+    if category in {"auth", "workspace"}:
+        return 3
+    return 4
+
+
+def _result_exit_code(result: dict[str, Any]) -> int:
+    if not isinstance(result, dict):
+        return 0
+    if result.get("ok") is False:
+        return 4
+    status = str(result.get("status") or "").lower()
+    if status in {"failed", "blocked"}:
+        return 4
+    return 0
+
+
+if __name__ == "__main__":
+    main()