@josephyan/qingflow-cli 0.2.0-beta.1000

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

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import argparse
+
+from ..context import CliContext
+from .common import parse_bool_text, raise_config_error
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser("import", help="导入")
+    import_subparsers = parser.add_subparsers(dest="import_command", required=True)
+
+    template = import_subparsers.add_parser("template", help="下载导入模板")
+    template.add_argument("--app-key", required=True)
+    template.add_argument("--download-to-path")
+    template.set_defaults(handler=_handle_template, format_hint="")
+
+    verify = import_subparsers.add_parser("verify", help="校验导入文件")
+    verify.add_argument("--app-key", required=True)
+    verify.add_argument("--file-path", required=True)
+    verify.set_defaults(handler=_handle_verify, format_hint="import_verify")
+
+    repair = import_subparsers.add_parser("repair", help="授权后修复导入文件")
+    repair.add_argument("--verification-id", required=True)
+    repair.add_argument("--authorized-file-modification", action="store_true")
+    repair.add_argument("--output-path")
+    repair.add_argument("--repair", dest="selected_repairs", action="append", default=[])
+    repair.set_defaults(handler=_handle_repair, format_hint="")
+
+    start = import_subparsers.add_parser("start", help="启动导入")
+    start.add_argument("--app-key", required=True)
+    start.add_argument("--verification-id", required=True)
+    start.add_argument("--being-enter-auditing", type=parse_bool_text, required=True)
+    start.add_argument("--view-key")
+    start.set_defaults(handler=_handle_start, format_hint="")
+
+    status = import_subparsers.add_parser("status", help="查询导入状态")
+    status.add_argument("--app-key")
+    status.add_argument("--import-id")
+    status.add_argument("--process-id-str")
+    status.set_defaults(handler=_handle_status, format_hint="import_status")
+
+
+def _handle_template(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.imports.record_import_template_get(
+        profile=args.profile,
+        app_key=args.app_key,
+        download_to_path=args.download_to_path,
+    )
+
+
+def _handle_verify(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.imports.record_import_verify(
+        profile=args.profile,
+        app_key=args.app_key,
+        file_path=args.file_path,
+    )
+
+
+def _handle_repair(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.imports.record_import_repair_local(
+        profile=args.profile,
+        verification_id=args.verification_id,
+        authorized_file_modification=bool(args.authorized_file_modification),
+        output_path=args.output_path,
+        selected_repairs=list(args.selected_repairs or []),
+    )
+
+
+def _handle_start(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.imports.record_import_start(
+        profile=args.profile,
+        app_key=args.app_key,
+        verification_id=args.verification_id,
+        being_enter_auditing=bool(args.being_enter_auditing),
+        view_key=args.view_key,
+    )
+
+
+def _handle_status(args: argparse.Namespace, context: CliContext) -> dict:
+    selectors = [
+        bool((args.app_key or "").strip()),
+        bool((args.import_id or "").strip()),
+        bool((args.process_id_str or "").strip()),
+    ]
+    if sum(selectors) != 1:
+        raise_config_error(
+            "import status accepts exactly one selector: --process-id-str, --import-id, or --app-key.",
+            fix_hint="Use `--process-id-str` or `--import-id` for a known import, or use only `--app-key` to read the latest import in that app.",
+        )
+    return context.imports.record_import_status_get(
+        profile=args.profile,
+        app_key=args.app_key,
+        import_id=args.import_id,
+        process_id_str=args.process_id_str,
+    )

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

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import argparse
+
+from ..context import CliContext
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser("portal", help="门户访问")
+    portal_subparsers = parser.add_subparsers(dest="portal_command", required=True)
+
+    list_parser = portal_subparsers.add_parser("list", help="列出当前用户可访问的门户")
+    list_parser.set_defaults(handler=_handle_list, format_hint="generic")
+
+    get_parser = portal_subparsers.add_parser("get", help="读取门户内容清单")
+    get_parser.add_argument("--dash-key", required=True)
+    get_parser.set_defaults(handler=_handle_get, format_hint="generic")
+
+
+def _handle_list(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.resource.portal_list(profile=args.profile)
+
+
+def _handle_get(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.resource.portal_get(profile=args.profile, dash_key=args.dash_key)

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

@@ -0,0 +1,331 @@
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from ...errors import QingflowApiError
+from ..context import CliContext
+from .common import load_list_arg, load_object_arg, raise_config_error, require_list_arg, require_object_arg
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser("record", help="记录与表结构")
+    record_subparsers = parser.add_subparsers(dest="record_command", required=True)
+
+    schema = record_subparsers.add_parser("schema", help="读取记录相关表结构")
+    schema.add_argument("--mode", dest="legacy_mode", help=argparse.SUPPRESS)
+    schema_subparsers = schema.add_subparsers(dest="record_schema_command")
+    schema.set_defaults(handler=_handle_schema_root, format_hint="")
+
+    schema_applicant = schema_subparsers.add_parser("applicant", help="读取申请节点表结构")
+    schema_applicant.add_argument("--app-key", required=True)
+    schema_applicant.set_defaults(handler=_handle_schema_applicant, format_hint="")
+
+    schema_browse = schema_subparsers.add_parser("browse", help="读取浏览视图表结构")
+    schema_browse.add_argument("--app-key", required=True)
+    schema_browse.add_argument("--view-id", required=True)
+    schema_browse.set_defaults(handler=_handle_schema_browse, format_hint="")
+
+    schema_insert = schema_subparsers.add_parser("insert", help="读取新增记录表结构")
+    schema_insert.add_argument("--app-key", required=True)
+    schema_insert.set_defaults(handler=_handle_schema_insert, format_hint="")
+
+    schema_update = schema_subparsers.add_parser("update", help="读取更新记录表结构")
+    schema_update.add_argument("--app-key", required=True)
+    schema_update.add_argument("--record-id", required=True)
+    schema_update.set_defaults(handler=_handle_schema_update, format_hint="")
+
+    schema_import = schema_subparsers.add_parser("import", help="读取导入表结构")
+    schema_import.add_argument("--app-key", required=True)
+    schema_import.set_defaults(handler=_handle_schema_import, format_hint="")
+
+    schema_code_block = schema_subparsers.add_parser("code-block", help="读取代码块执行表结构")
+    schema_code_block.add_argument("--app-key", required=True)
+    schema_code_block.set_defaults(handler=_handle_schema_code_block, format_hint="")
+
+    list_parser = record_subparsers.add_parser("list", help="列出记录")
+    list_parser.add_argument("--app-key", required=True)
+    list_parser.add_argument("--column", dest="columns", action="append", type=int, default=[])
+    list_parser.add_argument("--columns-file")
+    list_parser.add_argument("--where-file")
+    list_parser.add_argument("--order-by-file")
+    list_parser.add_argument("--limit", type=int, default=20)
+    list_parser.add_argument("--page", type=int, default=1)
+    list_parser.add_argument("--view-id")
+    list_parser.add_argument("--list-type", dest="legacy_list_type", type=int, help=argparse.SUPPRESS)
+    list_parser.add_argument("--view-key", dest="legacy_view_key", help=argparse.SUPPRESS)
+    list_parser.add_argument("--view-name", dest="legacy_view_name", help=argparse.SUPPRESS)
+    list_parser.set_defaults(handler=_handle_list, format_hint="record_list")
+
+    get = record_subparsers.add_parser("get", help="读取单条记录")
+    get.add_argument("--app-key", required=True)
+    get.add_argument("--record-id", required=True)
+    get.add_argument("--column", dest="columns", action="append", type=int, default=[])
+    get.add_argument("--columns-file")
+    get.add_argument("--view-id")
+    get.set_defaults(handler=_handle_get, format_hint="")
+
+    insert = record_subparsers.add_parser("insert", help="新增记录")
+    insert.add_argument("--app-key", required=True)
+    insert.add_argument("--fields-file", required=True)
+    insert.add_argument("--verify-write", action=argparse.BooleanOptionalAction, default=True)
+    insert.set_defaults(handler=_handle_insert, format_hint="")
+
+    update = record_subparsers.add_parser("update", help="更新记录")
+    update.add_argument("--app-key", required=True)
+    update.add_argument("--record-id")
+    update.add_argument("--fields-file")
+    update.add_argument("--items-file")
+    update.add_argument("--dry-run", action=argparse.BooleanOptionalAction, default=False)
+    update.add_argument("--verify-write", action=argparse.BooleanOptionalAction, default=True)
+    update.set_defaults(handler=_handle_update, format_hint="")
+
+    delete = record_subparsers.add_parser("delete", help="删除记录")
+    delete.add_argument("--app-key", required=True)
+    delete.add_argument("--record-id")
+    delete.add_argument("--record-ids-file")
+    delete.set_defaults(handler=_handle_delete, format_hint="")
+
+    analyze = record_subparsers.add_parser("analyze", help="分析记录数据")
+    analyze.add_argument("--app-key", required=True)
+    analyze.add_argument("--dimensions-file")
+    analyze.add_argument("--metrics-file")
+    analyze.add_argument("--filters-file")
+    analyze.add_argument("--sort-file")
+    analyze.add_argument("--limit", type=int, default=20)
+    analyze.add_argument("--strict-full", action=argparse.BooleanOptionalAction, default=False)
+    analyze.add_argument("--view-id")
+    analyze.add_argument("--list-type", dest="legacy_list_type", type=int, help=argparse.SUPPRESS)
+    analyze.add_argument("--view-key", dest="legacy_view_key", help=argparse.SUPPRESS)
+    analyze.add_argument("--view-name", dest="legacy_view_name", help=argparse.SUPPRESS)
+    analyze.set_defaults(handler=_handle_analyze, format_hint="")
+
+    code_block = record_subparsers.add_parser("code-block-run", help="执行代码块字段")
+    code_block.add_argument("--app-key", required=True)
+    code_block.add_argument("--record-id", required=True)
+    code_block.add_argument("--code-block-field", required=True)
+    code_block.add_argument("--role", type=int, default=1)
+    code_block.add_argument("--workflow-node-id", type=int)
+    code_block.add_argument("--answers-file")
+    code_block.add_argument("--fields-file")
+    code_block.add_argument("--manual", action=argparse.BooleanOptionalAction, default=True)
+    code_block.add_argument("--apply-writeback", action=argparse.BooleanOptionalAction, default=True)
+    code_block.add_argument("--verify-writeback", action=argparse.BooleanOptionalAction, default=True)
+    code_block.add_argument("--force-refresh-form", action="store_true")
+    code_block.set_defaults(handler=_handle_code_block_run, format_hint="")
+
+
+def _columns(args: argparse.Namespace) -> list[Any]:
+    columns: list[Any] = list(args.columns or [])
+    if args.columns_file:
+        columns.extend(require_list_arg(args.columns_file, option_name="--columns-file"))
+    return columns
+
+
+def _handle_schema_root(args: argparse.Namespace, _context: CliContext) -> dict:
+    mode = (args.legacy_mode or "").strip()
+    if mode:
+        replacement = {
+            "applicant": "record schema applicant --app-key APP_KEY",
+            "browse": "record schema browse --app-key APP_KEY --view-id VIEW_ID",
+            "insert": "record schema insert --app-key APP_KEY",
+            "update": "record schema update --app-key APP_KEY --record-id RECORD_ID",
+            "import": "record schema import --app-key APP_KEY",
+            "code-block": "record schema code-block --app-key APP_KEY",
+        }.get(mode, "record schema <applicant|browse|insert|update|import|code-block> ...")
+        raise_config_error(
+            "record schema --mode is no longer accepted.",
+            fix_hint=f"Use `{replacement}` instead.",
+        )
+    raise_config_error(
+        "record schema requires an explicit subcommand.",
+        fix_hint="Use one of: `record schema applicant`, `record schema browse`, `record schema insert`, `record schema update`, `record schema import`, or `record schema code-block`.",
+    )
+
+
+def _handle_schema_applicant(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.record.record_schema_get(
+        profile=args.profile,
+        app_key=args.app_key,
+        schema_mode="applicant",
+    )
+
+
+def _handle_schema_browse(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.record.record_browse_schema_get_public(
+        profile=args.profile,
+        app_key=args.app_key,
+        view_id=args.view_id,
+    )
+
+
+def _handle_schema_insert(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.record.record_insert_schema_get_public(profile=args.profile, app_key=args.app_key)
+
+
+def _handle_schema_update(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.record.record_update_schema_get_public(
+        profile=args.profile,
+        app_key=args.app_key,
+        record_id=args.record_id,
+    )
+
+
+def _handle_schema_import(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.imports.record_import_schema_get(profile=args.profile, app_key=args.app_key)
+
+
+def _handle_schema_code_block(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.code_block.record_code_block_schema_get_public(profile=args.profile, app_key=args.app_key)
+
+
+def _validate_public_view_selector(
+    *,
+    view_id: str | None,
+    legacy_list_type: int | None,
+    legacy_view_key: str | None,
+    legacy_view_name: str | None,
+    tool_name: str,
+) -> None:
+    if legacy_list_type is not None:
+        raise_config_error(
+            f"{tool_name} no longer accepts list_type.",
+            fix_hint="Call `app_get` first and use `accessible_views[].view_id`.",
+        )
+    if legacy_view_key or legacy_view_name:
+        raise_config_error(
+            f"{tool_name} no longer accepts view_key or view_name.",
+            fix_hint="Call `app_get` first and pass the exact `view_id` from `accessible_views`.",
+        )
+    if not (view_id or "").strip():
+        raise_config_error(
+            f"{tool_name} requires view_id.",
+            fix_hint="Call `app_get` first and choose one `accessible_views[].view_id`, then retry with `--view-id`.",
+        )
+
+
+def _handle_list(args: argparse.Namespace, context: CliContext) -> dict:
+    _validate_public_view_selector(
+        view_id=args.view_id,
+        legacy_list_type=args.legacy_list_type,
+        legacy_view_key=args.legacy_view_key,
+        legacy_view_name=args.legacy_view_name,
+        tool_name="record_list",
+    )
+    return context.record.record_list(
+        profile=args.profile,
+        app_key=args.app_key,
+        columns=_columns(args),
+        where=load_list_arg(args.where_file, option_name="--where-file"),
+        order_by=load_list_arg(args.order_by_file, option_name="--order-by-file"),
+        limit=args.limit,
+        page=args.page,
+        view_id=args.view_id,
+    )
+
+
+def _handle_get(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.record.record_get_public(
+        profile=args.profile,
+        app_key=args.app_key,
+        record_id=args.record_id,
+        columns=_columns(args),
+        view_id=args.view_id,
+    )
+
+
+def _handle_insert(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.record.record_insert_public(
+        profile=args.profile,
+        app_key=args.app_key,
+        fields=require_object_arg(args.fields_file, option_name="--fields-file"),
+        verify_write=bool(args.verify_write),
+    )
+
+
+def _handle_update(args: argparse.Namespace, context: CliContext) -> dict:
+    if args.items_file:
+        if args.record_id is not None or args.fields_file:
+            raise_config_error(
+                "record update batch mode does not accept --record-id or --fields-file.",
+                fix_hint="Use `record update --app-key APP_KEY --items-file ITEMS.json [--dry-run]` for batch updates.",
+            )
+        return context.record.record_update_public(
+            profile=args.profile,
+            app_key=args.app_key,
+            record_id=None,
+            fields=None,
+            items=require_list_arg(args.items_file, option_name="--items-file"),
+            dry_run=bool(args.dry_run),
+            verify_write=bool(args.verify_write),
+        )
+    if args.dry_run:
+        raise_config_error(
+            "record update --dry-run currently requires --items-file.",
+            fix_hint="Use `record update --app-key APP_KEY --items-file ITEMS.json --dry-run` for batch preflight.",
+        )
+    if args.record_id is None or not args.fields_file:
+        raise_config_error(
+            "record update single mode requires --record-id and --fields-file.",
+            fix_hint="Use `record update --app-key APP_KEY --record-id RECORD_ID --fields-file FIELDS.json`.",
+        )
+    return context.record.record_update_public(
+        profile=args.profile,
+        app_key=args.app_key,
+        record_id=args.record_id,
+        fields=require_object_arg(args.fields_file, option_name="--fields-file"),
+        verify_write=bool(args.verify_write),
+    )
+
+
+def _handle_delete(args: argparse.Namespace, context: CliContext) -> dict:
+    record_ids = load_list_arg(args.record_ids_file, option_name="--record-ids-file")
+    return context.record.record_delete_public(
+        profile=args.profile,
+        app_key=args.app_key,
+        record_id=args.record_id,
+        record_ids=record_ids,
+    )
+
+
+def _handle_analyze(args: argparse.Namespace, context: CliContext) -> dict:
+    _validate_public_view_selector(
+        view_id=args.view_id,
+        legacy_list_type=args.legacy_list_type,
+        legacy_view_key=args.legacy_view_key,
+        legacy_view_name=args.legacy_view_name,
+        tool_name="record_analyze",
+    )
+    return context.record.record_analyze(
+        profile=args.profile,
+        app_key=args.app_key,
+        dimensions=load_list_arg(args.dimensions_file, option_name="--dimensions-file"),
+        metrics=load_list_arg(args.metrics_file, option_name="--metrics-file"),
+        filters=load_list_arg(args.filters_file, option_name="--filters-file"),
+        sort=load_list_arg(args.sort_file, option_name="--sort-file"),
+        limit=args.limit,
+        strict_full=bool(args.strict_full),
+        view_id=args.view_id,
+    )
+
+
+def _handle_code_block_run(args: argparse.Namespace, context: CliContext) -> dict:
+    if args.workflow_node_id is not None and args.role != 3:
+        raise_config_error(
+            "workflow_node_id is only accepted when role=3.",
+            fix_hint="Remove `--workflow-node-id`, or set `--role 3` when running in workflow context.",
+        )
+    return context.code_block.record_code_block_run(
+        profile=args.profile,
+        app_key=args.app_key,
+        record_id=args.record_id,
+        code_block_field=args.code_block_field,
+        role=args.role,
+        workflow_node_id=args.workflow_node_id,
+        answers=load_list_arg(args.answers_file, option_name="--answers-file"),
+        fields=load_object_arg(args.fields_file, option_name="--fields-file") or {},
+        manual=bool(args.manual),
+        apply_writeback=bool(args.apply_writeback),
+        verify_writeback=bool(args.verify_writeback),
+        force_refresh_form=bool(args.force_refresh_form),
+    )

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

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import argparse
+
+from ..context import CliContext
+from .common import raise_config_error, require_list_arg, require_object_arg
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser("repo", help="代码仓库开发工具")
+    repo_subparsers = parser.add_subparsers(dest="repo_command", required=True)
+
+    init_parser = repo_subparsers.add_parser("init", help="从模板初始化仓库")
+    init_parser.add_argument("--group-name", required=True)
+    init_parser.add_argument("--repo-template", required=True)
+    init_parser.set_defaults(handler=_handle_init, format_hint="generic")
+
+    generate_parser = repo_subparsers.add_parser("generate", help="沿用官方 generate 链路生成并提交页面代码")
+    generate_parser.add_argument("--repo-name", required=True)
+    generate_parser.add_argument("--query", required=True)
+    generate_parser.add_argument("--tag-id", type=int)
+    generate_parser.add_argument("--app-keys-file")
+    generate_parser.add_argument("--extra-info-file")
+    generate_parser.add_argument("--file-messages-file")
+    generate_parser.add_argument("--agent-id", type=int)
+    generate_parser.add_argument("--allow-create-table", action="store_true")
+    generate_parser.add_argument("--route-prefix")
+    generate_parser.add_argument("--token-name")
+    generate_parser.add_argument("--session-id")
+    generate_parser.add_argument("--round-version", type=int)
+    generate_parser.add_argument("--disable-trace-log", action="store_true")
+    generate_parser.set_defaults(handler=_handle_generate, format_hint="generic")
+
+    publish_parser = repo_subparsers.add_parser("publish-prod", help="发布 develop 到生产分支")
+    publish_parser.add_argument("--repo-name", required=True)
+    publish_parser.add_argument("--confirm", action="store_true")
+    publish_parser.set_defaults(handler=_handle_publish_prod, format_hint="generic")
+
+
+def _handle_init(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.repo.repository_init(
+        profile=args.profile,
+        group_name=args.group_name,
+        repo_template=args.repo_template,
+    )
+
+
+def _handle_generate(args: argparse.Namespace, context: CliContext) -> dict:
+    app_keys = require_list_arg(args.app_keys_file, option_name="--app-keys-file") if args.app_keys_file else []
+    extra_info = require_object_arg(args.extra_info_file, option_name="--extra-info-file") if args.extra_info_file else None
+    file_messages = require_list_arg(args.file_messages_file, option_name="--file-messages-file") if args.file_messages_file else []
+    return context.repo.repository_generate(
+        profile=args.profile,
+        repo_name=args.repo_name,
+        query=args.query,
+        tag_id=args.tag_id,
+        app_keys=app_keys,
+        extra_info=extra_info,
+        file_messages=file_messages,
+        being_trace_log_enabled=not args.disable_trace_log,
+        agent_id=args.agent_id,
+        allow_create_table=args.allow_create_table,
+        route_prefix=args.route_prefix,
+        token_name=args.token_name,
+        session_id=args.session_id,
+        round_version=args.round_version,
+    )
+
+
+def _handle_publish_prod(args: argparse.Namespace, context: CliContext) -> dict:
+    if args.confirm is not True:
+        raise_config_error(
+            "repository_publish_prod requires explicit confirmation.",
+            fix_hint="Re-run with `--confirm` after verifying the target repo and release intent.",
+        )
+    return context.repo.repository_publish_prod(
+        profile=args.profile,
+        repo_name=args.repo_name,
+        confirm=args.confirm,
+    )

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

@@ -0,0 +1,141 @@
+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",
+        help="先走后端待办检索；当后端返回零结果时，公开 task_list 会回退到本地匹配 app_name / workflow_node_name / app_key / record_id。",
+    )
+    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="读取待办详情；推荐直接传 --task-id")
+    get.add_argument("--task-id")
+    get.add_argument("--app-key")
+    get.add_argument("--record-id")
+    get.add_argument("--workflow-node-id", 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="task_get")
+
+    action = task_subparsers.add_parser("action", help="执行待办动作")
+    action.add_argument("--task-id")
+    action.add_argument("--app-key")
+    action.add_argument("--record-id")
+    action.add_argument("--workflow-node-id", type=int)
+    action.add_argument("--action", required=True)
+    action.add_argument("--payload-file")
+    action.add_argument("--fields-file")
+    action.set_defaults(
+        handler=_handle_action,
+        format_hint="task_action_execute",
+        hide_effective_context_line=True,
+    )
+
+    report = task_subparsers.add_parser("report", help="读取待办关联报表详情；推荐直接传 --task-id")
+    report.add_argument("--task-id")
+    report.add_argument("--app-key")
+    report.add_argument("--record-id")
+    report.add_argument("--workflow-node-id", type=int)
+    report.add_argument("--report-id", required=True, type=int)
+    report.add_argument("--page", type=int, default=1)
+    report.add_argument("--page-size", type=int, default=20)
+    report.set_defaults(handler=_handle_report, format_hint="task_associated_report_detail_get")
+
+    log = task_subparsers.add_parser("log", help="读取流程日志；推荐直接传 --task-id")
+    log.add_argument("--task-id")
+    log.add_argument("--app-key")
+    log.add_argument("--record-id")
+    log.add_argument("--workflow-node-id", 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:
+    if not args.task_id and not (args.app_key and args.record_id and args.workflow_node_id):
+        raise RuntimeError(
+            '{"category":"config","message":"task get requires --task-id, or --app-key together with --record-id and --workflow-node-id"}'
+        )
+    return context.task.task_get(
+        profile=args.profile,
+        task_id=args.task_id,
+        app_key=args.app_key or "",
+        record_id=args.record_id or "",
+        workflow_node_id=int(args.workflow_node_id or 0),
+        include_candidates=bool(args.include_candidates),
+        include_associated_reports=bool(args.include_associated_reports),
+    )
+
+
+def _handle_action(args: argparse.Namespace, context: CliContext) -> dict:
+    if not args.task_id and not (args.app_key and args.record_id and args.workflow_node_id):
+        raise RuntimeError(
+            '{"category":"config","message":"task action requires --task-id, or --app-key together with --record-id and --workflow-node-id"}'
+        )
+    return context.task.task_action_execute(
+        profile=args.profile,
+        task_id=args.task_id,
+        app_key=args.app_key or "",
+        record_id=args.record_id or "",
+        workflow_node_id=int(args.workflow_node_id or 0),
+        action=args.action,
+        payload=load_object_arg(args.payload_file, option_name="--payload-file") or {},
+        fields=load_object_arg(args.fields_file, option_name="--fields-file") or {},
+    )
+
+
+def _handle_log(args: argparse.Namespace, context: CliContext) -> dict:
+    if not args.task_id and not (args.app_key and args.record_id and args.workflow_node_id):
+        raise RuntimeError(
+            '{"category":"config","message":"task log requires --task-id, or --app-key together with --record-id and --workflow-node-id"}'
+        )
+    return context.task.task_workflow_log_get(
+        profile=args.profile,
+        task_id=args.task_id,
+        app_key=args.app_key or "",
+        record_id=args.record_id or "",
+        workflow_node_id=int(args.workflow_node_id or 0),
+    )
+
+
+def _handle_report(args: argparse.Namespace, context: CliContext) -> dict:
+    if not args.task_id and not (args.app_key and args.record_id and args.workflow_node_id):
+        raise RuntimeError(
+            '{"category":"config","message":"task report requires --task-id, or --app-key together with --record-id and --workflow-node-id"}'
+        )
+    return context.task.task_associated_report_detail_get(
+        profile=args.profile,
+        task_id=args.task_id,
+        app_key=args.app_key or "",
+        record_id=args.record_id or "",
+        workflow_node_id=int(args.workflow_node_id or 0),
+        report_id=int(args.report_id),
+        page=int(args.page),
+        page_size=int(args.page_size),
+    )