@josephyan/qingflow-cli 0.2.0-beta.69 → 0.2.0-beta.70

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

@@ -3,13 +3,42 @@ from __future__ import annotations
 import argparse
 
 from ..context import CliContext
-from .common import load_list_arg, load_object_arg, require_list_arg
+from .common import load_list_arg, load_object_arg, raise_config_error, require_list_arg
 
 
 def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
     parser = subparsers.add_parser("builder", aliases=["build"], help="稳定 builder 命令")
     builder_subparsers = parser.add_subparsers(dest="builder_command", required=True)
 
+    contract = builder_subparsers.add_parser("contract", help="读取 builder tool 合约")
+    contract.add_argument("--tool-name", required=True)
+    contract.set_defaults(handler=_handle_contract, format_hint="builder_summary")
+
+    member = builder_subparsers.add_parser("member", help="成员目录")
+    member_subparsers = member.add_subparsers(dest="builder_member_command", required=True)
+    member_search = member_subparsers.add_parser("search", help="搜索成员")
+    member_search.add_argument("--query", default="")
+    member_search.add_argument("--page-num", type=int, default=1)
+    member_search.add_argument("--page-size", type=int, default=20)
+    member_search.add_argument("--contain-disable", action=argparse.BooleanOptionalAction, default=False)
+    member_search.set_defaults(handler=_handle_member_search, format_hint="builder_summary")
+
+    role = builder_subparsers.add_parser("role", help="角色目录")
+    role_subparsers = role.add_subparsers(dest="builder_role_command", required=True)
+    role_search = role_subparsers.add_parser("search", help="搜索角色")
+    role_search.add_argument("--keyword", default="")
+    role_search.add_argument("--page-num", type=int, default=1)
+    role_search.add_argument("--page-size", type=int, default=20)
+    role_search.set_defaults(handler=_handle_role_search, format_hint="builder_summary")
+
+    role_create = role_subparsers.add_parser("create", help="创建角色")
+    role_create.add_argument("--role-name", required=True)
+    role_create.add_argument("--member-uids-file")
+    role_create.add_argument("--member-emails-file")
+    role_create.add_argument("--member-names-file")
+    role_create.add_argument("--role-icon", default="ex-user-outlined")
+    role_create.set_defaults(handler=_handle_role_create, format_hint="builder_summary")
+
     package = builder_subparsers.add_parser("package", help="应用包")
     package_subparsers = package.add_subparsers(dest="builder_package_command", required=True)
     package_list = package_subparsers.add_parser("list", help="列出应用包")
@@ -26,6 +55,12 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     package_create.add_argument("--color")
     package_create.set_defaults(handler=_handle_package_create, format_hint="builder_summary")
 
+    package_attach_app = package_subparsers.add_parser("attach-app", help="将应用挂载到应用包")
+    package_attach_app.add_argument("--tag-id", type=int, required=True)
+    package_attach_app.add_argument("--app-key", required=True)
+    package_attach_app.add_argument("--app-title", dest="legacy_app_title", help=argparse.SUPPRESS)
+    package_attach_app.set_defaults(handler=_handle_package_attach_app, format_hint="builder_summary")
+
     app = builder_subparsers.add_parser("app", help="应用")
     app_subparsers = app.add_subparsers(dest="builder_app_command", required=True)
 
@@ -35,6 +70,12 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     app_resolve.add_argument("--package-tag-id", type=int)
     app_resolve.set_defaults(handler=_handle_app_resolve, format_hint="builder_summary")
 
+    app_release_lock = app_subparsers.add_parser("release-edit-lock-if-mine", help="释放当前账号持有的编辑锁")
+    app_release_lock.add_argument("--app-key", required=True)
+    app_release_lock.add_argument("--lock-owner-email", required=True)
+    app_release_lock.add_argument("--lock-owner-name", required=True)
+    app_release_lock.set_defaults(handler=_handle_app_release_edit_lock_if_mine, format_hint="builder_summary")
+
     button = builder_subparsers.add_parser("button", help="自定义按钮")
     button_subparsers = button.add_subparsers(dest="builder_button_command", required=True)
 
@@ -77,6 +118,14 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
 
     portal = builder_subparsers.add_parser("portal", help="门户")
     portal_subparsers = portal.add_subparsers(dest="builder_portal_command", required=True)
+    portal_list = portal_subparsers.add_parser("list", help="列出可访问门户")
+    portal_list.set_defaults(handler=_handle_portal_list, format_hint="builder_summary")
+
+    portal_get = portal_subparsers.add_parser("get", help="读取门户详情")
+    portal_get.add_argument("--dash-key", required=True)
+    portal_get.add_argument("--being-draft", action=argparse.BooleanOptionalAction, default=True)
+    portal_get.set_defaults(handler=_handle_portal_get, format_hint="builder_summary")
+
     portal_read = portal_subparsers.add_parser("read-summary", help="读取门户摘要")
     portal_read.add_argument("--dash-key", required=True)
     portal_read.add_argument("--being-draft", action=argparse.BooleanOptionalAction, default=True)
@@ -112,6 +161,34 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     schema_apply_apply.add_argument("--remove-fields-file")
     schema_apply_apply.set_defaults(handler=_handle_schema_apply, format_hint="builder_summary")
 
+    layout_apply = builder_subparsers.add_parser("layout", help="布局")
+    layout_apply_subparsers = layout_apply.add_subparsers(dest="builder_layout_command", required=True)
+    layout_apply_apply = layout_apply_subparsers.add_parser("apply", help="执行布局变更")
+    layout_apply_apply.add_argument("--app-key", required=True)
+    layout_apply_apply.add_argument("--mode", choices=["merge", "replace"], default="merge")
+    layout_apply_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=True)
+    layout_apply_apply.add_argument("--sections-file", required=True)
+    layout_apply_apply.set_defaults(handler=_handle_layout_apply, format_hint="builder_summary")
+
+    views_apply = builder_subparsers.add_parser("views", help="视图")
+    views_apply_subparsers = views_apply.add_subparsers(dest="builder_views_command", required=True)
+    views_apply_apply = views_apply_subparsers.add_parser("apply", help="执行视图变更")
+    views_apply_apply.add_argument("--app-key", required=True)
+    views_apply_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=True)
+    views_apply_apply.add_argument("--upsert-views-file")
+    views_apply_apply.add_argument("--remove-views-file")
+    views_apply_apply.set_defaults(handler=_handle_views_apply, format_hint="builder_summary")
+
+    flow_apply = builder_subparsers.add_parser("flow", help="流程")
+    flow_apply_subparsers = flow_apply.add_subparsers(dest="builder_flow_command", required=True)
+    flow_apply_apply = flow_apply_subparsers.add_parser("apply", help="执行流程变更")
+    flow_apply_apply.add_argument("--app-key", required=True)
+    flow_apply_apply.add_argument("--mode", choices=["replace"], default="replace")
+    flow_apply_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=True)
+    flow_apply_apply.add_argument("--nodes-file", required=True)
+    flow_apply_apply.add_argument("--transitions-file", required=True)
+    flow_apply_apply.set_defaults(handler=_handle_flow_apply, format_hint="builder_summary")
+
     charts_apply = builder_subparsers.add_parser("charts", help="报表")
     charts_apply_subparsers = charts_apply.add_subparsers(dest="builder_charts_command", required=True)
     charts_apply_apply = charts_apply_subparsers.add_parser("apply", help="执行报表变更")
@@ -128,11 +205,62 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     publish_verify_verify.add_argument("--expected-package-tag-id", type=int)
     publish_verify_verify.set_defaults(handler=_handle_publish_verify, format_hint="builder_summary")
 
+    view = builder_subparsers.add_parser("view", help="视图详情")
+    view_subparsers = view.add_subparsers(dest="builder_view_command", required=True)
+    view_get = view_subparsers.add_parser("get", help="读取视图详情")
+    view_get.add_argument("--viewgraph-key", required=True)
+    view_get.set_defaults(handler=_handle_view_get, format_hint="builder_summary")
+
+    chart = builder_subparsers.add_parser("chart", help="报表详情")
+    chart_subparsers = chart.add_subparsers(dest="builder_chart_command", required=True)
+    chart_get = chart_subparsers.add_parser("get", help="读取报表详情和数据")
+    chart_get.add_argument("--chart-id", required=True)
+    chart_get.add_argument("--data-payload-file")
+    chart_get.add_argument("--page-num", type=int)
+    chart_get.add_argument("--page-size", type=int)
+    chart_get.add_argument("--page-num-y", type=int)
+    chart_get.add_argument("--page-size-y", type=int)
+    chart_get.set_defaults(handler=_handle_chart_get, format_hint="builder_summary")
+
 
 def _handle_package_list(args: argparse.Namespace, context: CliContext) -> dict:
     return context.builder.package_list(profile=args.profile, trial_status=args.trial_status)
 
 
+def _handle_contract(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.builder_tool_contract(tool_name=args.tool_name)
+
+
+def _handle_member_search(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.member_search(
+        profile=args.profile,
+        query=args.query,
+        page_num=args.page_num,
+        page_size=args.page_size,
+        contain_disable=bool(args.contain_disable),
+    )
+
+
+def _handle_role_search(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.role_search(
+        profile=args.profile,
+        keyword=args.keyword,
+        page_num=args.page_num,
+        page_size=args.page_size,
+    )
+
+
+def _handle_role_create(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.role_create(
+        profile=args.profile,
+        role_name=args.role_name,
+        member_uids=load_list_arg(args.member_uids_file, option_name="--member-uids-file"),
+        member_emails=load_list_arg(args.member_emails_file, option_name="--member-emails-file"),
+        member_names=load_list_arg(args.member_names_file, option_name="--member-names-file"),
+        role_icon=args.role_icon,
+    )
+
+
 def _handle_package_resolve(args: argparse.Namespace, context: CliContext) -> dict:
     return context.builder.package_resolve(profile=args.profile, package_name=args.package_name)
 
@@ -146,7 +274,33 @@ def _handle_package_create(args: argparse.Namespace, context: CliContext) -> dic
     )
 
 
+def _handle_package_attach_app(args: argparse.Namespace, context: CliContext) -> dict:
+    if (args.legacy_app_title or "").strip():
+        raise_config_error(
+            "package attach-app no longer accepts app_title.",
+            fix_hint="Use `--app-key` to identify the app to attach.",
+        )
+    return context.builder.package_attach_app(
+        profile=args.profile,
+        tag_id=args.tag_id,
+        app_key=args.app_key,
+    )
+
+
 def _handle_app_resolve(args: argparse.Namespace, context: CliContext) -> dict:
+    has_app_key = bool((args.app_key or "").strip())
+    has_app_name = bool((args.app_name or "").strip())
+    has_package_tag_id = args.package_tag_id is not None
+    if has_app_key and (has_app_name or has_package_tag_id):
+        raise_config_error(
+            "app resolve accepts exactly one selector mode.",
+            fix_hint="Use only `--app-key`, or use `--app-name` together with `--package-tag-id`.",
+        )
+    if not has_app_key and not (has_app_name and has_package_tag_id):
+        raise_config_error(
+            "app resolve requires either --app-key, or --app-name together with --package-tag-id.",
+            fix_hint="For an existing known app, pass `--app-key`. For package-scoped lookup, pass both `--app-name` and `--package-tag-id`.",
+        )
     return context.builder.app_resolve(
         profile=args.profile,
         app_key=args.app_key,
@@ -155,6 +309,15 @@ def _handle_app_resolve(args: argparse.Namespace, context: CliContext) -> dict:
     )
 
 
+def _handle_app_release_edit_lock_if_mine(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_release_edit_lock_if_mine(
+        profile=args.profile,
+        app_key=args.app_key,
+        lock_owner_email=args.lock_owner_email,
+        lock_owner_name=args.lock_owner_name,
+    )
+
+
 def _handle_button_list(args: argparse.Namespace, context: CliContext) -> dict:
     return context.builder.app_custom_button_list(profile=args.profile, app_key=args.app_key)
 
@@ -208,6 +371,14 @@ def _handle_app_read_charts(args: argparse.Namespace, context: CliContext) -> di
     return context.builder.app_read_charts_summary(profile=args.profile, app_key=args.app_key)
 
 
+def _handle_portal_list(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.portal_list(profile=args.profile)
+
+
+def _handle_portal_get(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.portal_get(profile=args.profile, dash_key=args.dash_key, being_draft=bool(args.being_draft))
+
+
 def _handle_portal_read_summary(args: argparse.Namespace, context: CliContext) -> dict:
     return context.builder.portal_read_summary(
         profile=args.profile,
@@ -216,7 +387,39 @@ def _handle_portal_read_summary(args: argparse.Namespace, context: CliContext) -
     )
 
 
+def _handle_view_get(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.view_get(profile=args.profile, viewgraph_key=args.viewgraph_key)
+
+
+def _handle_chart_get(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.chart_get(
+        profile=args.profile,
+        chart_id=args.chart_id,
+        data_payload=load_object_arg(args.data_payload_file, option_name="--data-payload-file") if args.data_payload_file else {},
+        page_num=args.page_num,
+        page_size=args.page_size,
+        page_num_y=args.page_num_y,
+        page_size_y=args.page_size_y,
+    )
+
+
 def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
+    has_app_key = bool((args.app_key or "").strip())
+    has_app_name = bool((args.app_name or "").strip())
+    has_app_title = bool((args.app_title or "").strip())
+    has_package_tag_id = args.package_tag_id is not None
+    if has_app_key:
+        if args.create_if_missing or has_app_name or has_package_tag_id or has_app_title:
+            raise_config_error(
+                "schema apply edit mode only accepts --app-key as the resource selector.",
+                fix_hint="For existing apps, pass `--app-key` only. For create mode, use `--package-tag-id --app-name --create-if-missing`.",
+            )
+    else:
+        if not args.create_if_missing or not has_package_tag_id or not has_app_name:
+            raise_config_error(
+                "schema apply create mode requires --package-tag-id, --app-name, and --create-if-missing.",
+                fix_hint="Use `--app-key` for existing apps, or pass `--package-tag-id --app-name --create-if-missing` to create a new app.",
+            )
     return context.builder.app_schema_apply(
         profile=args.profile,
         app_key=args.app_key,
@@ -233,6 +436,37 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
     )
 
 
+def _handle_layout_apply(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_layout_apply(
+        profile=args.profile,
+        app_key=args.app_key,
+        mode=args.mode,
+        publish=bool(args.publish),
+        sections=require_list_arg(args.sections_file, option_name="--sections-file"),
+    )
+
+
+def _handle_views_apply(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_views_apply(
+        profile=args.profile,
+        app_key=args.app_key,
+        publish=bool(args.publish),
+        upsert_views=load_list_arg(args.upsert_views_file, option_name="--upsert-views-file"),
+        remove_views=load_list_arg(args.remove_views_file, option_name="--remove-views-file"),
+    )
+
+
+def _handle_flow_apply(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_flow_apply(
+        profile=args.profile,
+        app_key=args.app_key,
+        mode=args.mode,
+        publish=bool(args.publish),
+        nodes=require_list_arg(args.nodes_file, option_name="--nodes-file"),
+        transitions=require_list_arg(args.transitions_file, option_name="--transitions-file"),
+    )
+
+
 def _handle_charts_apply(args: argparse.Namespace, context: CliContext) -> dict:
     return context.builder.app_charts_apply(
         profile=args.profile,
@@ -244,6 +478,19 @@ def _handle_charts_apply(args: argparse.Namespace, context: CliContext) -> dict:
 
 
 def _handle_portal_apply(args: argparse.Namespace, context: CliContext) -> dict:
+    has_dash_key = bool((args.dash_key or "").strip())
+    has_dash_name = bool((args.dash_name or "").strip())
+    has_package_tag_id = args.package_tag_id is not None
+    if has_dash_key and has_package_tag_id:
+        raise_config_error(
+            "portal apply accepts exactly one selector mode.",
+            fix_hint="Use `--dash-key` to update an existing portal, or use `--package-tag-id --dash-name` to create a new portal.",
+        )
+    if not has_dash_key and not (has_package_tag_id and has_dash_name):
+        raise_config_error(
+            "portal apply requires either --dash-key, or --package-tag-id together with --dash-name.",
+            fix_hint="Use `--dash-key` for an existing portal. For create mode, pass `--package-tag-id --dash-name`.",
+        )
     return context.builder.portal_apply(
         profile=args.profile,
         dash_key=args.dash_key,

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

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import argparse
+import json
 import sys
 from typing import Any
 
@@ -45,3 +46,17 @@ def read_secret_arg(value: str | None, *, stdin_enabled: bool, label: str) -> st
     if value:
         return value
     raise QingflowApiError.config_error(f"{label} is required")
+
+
+def raise_config_error(message: str, *, fix_hint: str) -> None:
+    raise RuntimeError(
+        json.dumps(
+            {
+                "category": "config",
+                "message": message,
+                "error_code": "CONFIG_ERROR",
+                "details": {"fix_hint": fix_hint},
+            },
+            ensure_ascii=False,
+        )
+    )

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

@@ -3,7 +3,7 @@ from __future__ import annotations
 import argparse
 
 from ..context import CliContext
-from .common import parse_bool_text
+from .common import parse_bool_text, raise_config_error
 
 
 def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
@@ -35,7 +35,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     start.set_defaults(handler=_handle_start, format_hint="")
 
     status = import_subparsers.add_parser("status", help="查询导入状态")
-    status.add_argument("--app-key", required=True)
+    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")
@@ -78,6 +78,16 @@ def _handle_start(args: argparse.Namespace, context: CliContext) -> dict:
 
 
 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,

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

@@ -5,7 +5,7 @@ from typing import Any
 
 from ...errors import QingflowApiError
 from ..context import CliContext
-from .common import load_list_arg, load_object_arg, require_list_arg, require_object_arg
+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:
@@ -13,11 +13,35 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     record_subparsers = parser.add_subparsers(dest="record_command", required=True)
 
     schema = record_subparsers.add_parser("schema", help="读取记录相关表结构")
-    schema.add_argument("--app-key", required=True)
-    schema.add_argument("--mode", choices=["applicant", "browse", "insert", "update", "import", "code-block"], default="applicant")
-    schema.add_argument("--view-id")
-    schema.add_argument("--record-id", type=int)
-    schema.set_defaults(handler=_handle_schema, format_hint="")
+    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, type=int)
+    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)
@@ -28,6 +52,9 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     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="读取单条记录")
@@ -66,6 +93,9 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     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="执行代码块字段")
@@ -90,38 +120,96 @@ def _columns(args: argparse.Namespace) -> list[Any]:
     return columns
 
 
-def _handle_schema(args: argparse.Namespace, context: CliContext) -> dict:
-    mode = args.mode
-    if mode == "applicant":
-        return context.record.record_schema_get(
-            profile=args.profile,
-            app_key=args.app_key,
-            schema_mode="applicant",
+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 mode == "browse":
-        if not args.view_id:
-            raise QingflowApiError.config_error("--view-id is required when --mode browse")
-        return context.record.record_browse_schema_get_public(
-            profile=args.profile,
-            app_key=args.app_key,
-            view_id=args.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 mode == "insert":
-        return context.record.record_insert_schema_get_public(profile=args.profile, app_key=args.app_key)
-    if mode == "update":
-        if not args.record_id:
-            raise QingflowApiError.config_error("--record-id is required when --mode update")
-        return context.record.record_update_schema_get_public(
-            profile=args.profile,
-            app_key=args.app_key,
-            record_id=args.record_id,
+    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`.",
         )
-    if mode == "import":
-        return context.imports.record_import_schema_get(profile=args.profile, app_key=args.app_key)
-    return context.code_block.record_code_block_schema_get_public(profile=args.profile, app_key=args.app_key)
 
 
 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,
@@ -174,6 +262,13 @@ def _handle_delete(args: argparse.Namespace, context: CliContext) -> dict:
 
 
 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,
@@ -188,6 +283,11 @@ def _handle_analyze(args: argparse.Namespace, context: CliContext) -> dict:
 
 
 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,

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

@@ -17,7 +17,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
 
     select = workspace_subparsers.add_parser("select", help="切换工作区")
     select.add_argument("--ws-id", type=int, required=True)
-    select.set_defaults(handler=_handle_select, format_hint="")
+    select.set_defaults(handler=_handle_select, format_hint="workspace_select")
 
 
 def _handle_list(args: argparse.Namespace, context: CliContext) -> dict: