@josephyan/qingflow-app-builder-mcp 1.1.25 → 1.1.26

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

@@ -11,7 +11,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
 
     get_parser = chart_subparsers.add_parser("get", help="读取报表数据")
     get_parser.add_argument("--chart-id", required=True)
-    get_parser.set_defaults(handler=_handle_get, format_hint="chart_get")
+    get_parser.set_defaults(handler=_handle_get, format_hint="generic")
 
 
 def _handle_get(args: argparse.Namespace, context: CliContext) -> dict:

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

@@ -48,23 +48,14 @@ def read_secret_arg(value: str | None, *, stdin_enabled: bool, label: str) -> st
     raise QingflowApiError.config_error(f"{label} is required")
 
 
-def raise_config_error(
-    message: str,
-    *,
-    fix_hint: str | None = None,
-    error_code: str = "CONFIG_ERROR",
-    details: dict[str, Any] | None = None,
-) -> None:
-    error_details: dict[str, Any] = {"fix_hint": fix_hint or message}
-    if details:
-        error_details.update(details)
+def raise_config_error(message: str, *, fix_hint: str) -> None:
     raise RuntimeError(
         json.dumps(
             {
                 "category": "config",
                 "message": message,
-                "error_code": error_code,
-                "details": error_details,
+                "error_code": "CONFIG_ERROR",
+                "details": {"fix_hint": fix_hint},
             },
             ensure_ascii=False,
         )

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

@@ -12,7 +12,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
 
     start = export_subparsers.add_parser("start", help="启动导出")
     start.add_argument("--app-key", required=True)
-    start.add_argument("--view-id", required=True)
+    start.add_argument("--view-id", default="system:all")
     start.add_argument("--column", dest="columns", action="append", type=int, default=[], help="只导出这些 field_id；不传时导出当前视图全部字段")
     start.add_argument("--columns-file", help="JSON/YAML list，内容与 --column 语义一致")
     start.add_argument("--where-file", help="JSON/YAML list，内容与 record list 的 where DSL 一致；内部先查命中 record_id 再走原生导出")
@@ -33,7 +33,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
 
     direct = export_subparsers.add_parser("direct", help="直接导出并下载")
     direct.add_argument("--app-key", required=True)
-    direct.add_argument("--view-id", required=True)
+    direct.add_argument("--view-id", default="system:all")
     direct.add_argument("--column", dest="columns", action="append", type=int, default=[], help="只导出这些 field_id；不传时导出当前视图全部字段")
     direct.add_argument("--columns-file", help="JSON/YAML list，内容与 --column 语义一致")
     direct.add_argument("--where-file", help="JSON/YAML list，内容与 record list 的 where DSL 一致；内部先查命中 record_id 再走原生导出")

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

@@ -13,7 +13,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     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="import_template")
+    template.set_defaults(handler=_handle_template, format_hint="")
 
     verify = import_subparsers.add_parser("verify", help="校验导入文件")
     verify.add_argument("--app-key", required=True)
@@ -25,14 +25,14 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     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="import_repair")
+    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="import_start")
+    start.set_defaults(handler=_handle_start, format_hint="")
 
     status = import_subparsers.add_parser("status", help="查询导入状态")
     status.add_argument("--app-key")

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

@@ -10,11 +10,11 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     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="portal_list")
+    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="portal_get")
+    get_parser.set_defaults(handler=_handle_get, format_hint="generic")
 
 
 def _handle_list(args: argparse.Namespace, context: CliContext) -> dict:

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

@@ -18,43 +18,34 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
 
     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",
-        metavar="{browse,insert,update,import,code-block}",
-    )
+    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=argparse.SUPPRESS)
+    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="record_schema")
-    schema_subparsers._choices_actions = [  # type: ignore[attr-defined]
-        action
-        for action in schema_subparsers._choices_actions  # type: ignore[attr-defined]
-        if getattr(action, "dest", None) != "applicant"
-    ]
+    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="record_schema")
+    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="record_schema")
+    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.add_argument("--view-id")
-    schema_update.set_defaults(handler=_handle_schema_update, format_hint="record_schema")
+    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="record_schema")
+    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="record_schema")
+    schema_code_block.set_defaults(handler=_handle_schema_code_block, format_hint="")
 
     member_candidates = record_subparsers.add_parser("member-candidates", help="读取成员字段候选项")
     member_candidates.add_argument("--app-key", required=True)
@@ -65,7 +56,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     member_candidates.add_argument("--record-id")
     member_candidates.add_argument("--workflow-node-id", type=int)
     member_candidates.add_argument("--fields-file")
-    member_candidates.set_defaults(handler=_handle_member_candidates, format_hint="record_candidates")
+    member_candidates.set_defaults(handler=_handle_member_candidates, format_hint="")
 
     department_candidates = record_subparsers.add_parser("department-candidates", help="读取部门字段候选项")
     department_candidates.add_argument("--app-key", required=True)
@@ -76,41 +67,18 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     department_candidates.add_argument("--record-id")
     department_candidates.add_argument("--workflow-node-id", type=int)
     department_candidates.add_argument("--fields-file")
-    department_candidates.set_defaults(handler=_handle_department_candidates, format_hint="record_candidates")
+    department_candidates.set_defaults(handler=_handle_department_candidates, 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=[],
-        metavar="FIELD_ID",
-        help="只返回这些 field_id；可重复传",
-    )
-    list_parser.add_argument(
-        "--columns-file",
-        help="JSON/YAML list；元素为 field_id 整数/整数字符串或 {'field_id': ...}",
-    )
+    list_parser.add_argument("--column", dest="columns", action="append", type=int, default=[])
+    list_parser.add_argument("--columns-file")
     list_parser.add_argument("--query")
-    list_parser.add_argument(
-        "--query-field",
-        dest="query_fields",
-        action="append",
-        type=int,
-        default=[],
-        metavar="FIELD_ID",
-        help="全文搜索范围 field_id；可重复传",
-    )
-    list_parser.add_argument(
-        "--query-fields-file",
-        help="JSON/YAML list；元素为 field_id 整数/整数字符串或 {'field_id': ...}",
-    )
+    list_parser.add_argument("--query-field", dest="query_fields", action="append", type=int, default=[])
+    list_parser.add_argument("--query-fields-file")
     list_parser.add_argument("--where-file")
     list_parser.add_argument("--order-by-file")
     list_parser.add_argument("--page", type=int, default=1)
-    list_parser.add_argument("--page-size", type=int, default=10)
     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)
@@ -119,19 +87,8 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
 
     access_parser = record_subparsers.add_parser("access", help="访问记录并写入本地 CSV 分片")
     access_parser.add_argument("--app-key", required=True)
-    access_parser.add_argument(
-        "--column",
-        dest="columns",
-        action="append",
-        type=int,
-        default=[],
-        metavar="FIELD_ID",
-        help="导出这些 field_id 到 CSV；可重复传",
-    )
-    access_parser.add_argument(
-        "--columns-file",
-        help="JSON/YAML list；元素为 field_id 整数/整数字符串或 {'field_id': ...}",
-    )
+    access_parser.add_argument("--column", dest="columns", action="append", type=int, default=[])
+    access_parser.add_argument("--columns-file")
     access_parser.add_argument("--where-file")
     access_parser.add_argument("--order-by-file")
     access_parser.add_argument("--view-id", required=True)
@@ -140,26 +97,15 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     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=[],
-        metavar="FIELD_ID",
-        help="聚焦这些 field_id；可重复传",
-    )
-    get.add_argument(
-        "--columns-file",
-        help="JSON/YAML list；元素为 field_id 整数/整数字符串或 {'field_id': ...}",
-    )
+    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="record_get")
 
     logs = record_subparsers.add_parser("logs", help="读取单条记录全量日志并写入本地 JSONL")
     logs.add_argument("--app-key", required=True)
     logs.add_argument("--record-id", required=True)
-    logs.add_argument("--view-id", required=True)
+    logs.add_argument("--view-id")
     logs.set_defaults(handler=_handle_logs, format_hint="record_logs")
 
     insert = record_subparsers.add_parser("insert", help="新增记录")
@@ -167,25 +113,22 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     insert.add_argument("--fields-file", help=argparse.SUPPRESS)
     insert.add_argument("--items-file")
     insert.add_argument("--verify-write", action=argparse.BooleanOptionalAction, default=True)
-    insert.set_defaults(handler=_handle_insert, format_hint="record_write")
+    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("--view-id")
     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="record_write")
+    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.add_argument("--view-id")
-    delete.add_argument("--list-type", dest="legacy_list_type", type=int, help=argparse.SUPPRESS)
-    delete.set_defaults(handler=_handle_delete, format_hint="record_delete")
+    delete.set_defaults(handler=_handle_delete, format_hint="")
 
     analyze = record_subparsers.add_parser("analyze", help=argparse.SUPPRESS)
     record_subparsers._choices_actions = [  # type: ignore[attr-defined]
@@ -210,7 +153,6 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     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("--view-id")
     code_block.add_argument("--role", type=int, default=1)
     code_block.add_argument("--workflow-node-id", type=int)
     code_block.add_argument("--answers-file")
@@ -219,7 +161,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     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="code_block_run")
+    code_block.set_defaults(handler=_handle_code_block_run, format_hint="")
 
 
 def _columns(args: argparse.Namespace) -> list[Any]:
@@ -240,20 +182,20 @@ def _handle_schema_root(args: argparse.Namespace, _context: CliContext) -> dict:
     mode = (args.legacy_mode or "").strip()
     if mode:
         replacement = {
-            "applicant": "record schema insert --app-key APP_KEY",
+            "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 [--view-id VIEW_ID]",
+            "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 <browse|insert|update|import|code-block> ...")
+        }.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 browse`, `record schema insert`, `record schema update`, `record schema import`, or `record schema code-block`.",
+        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`.",
     )
 
 
@@ -282,7 +224,6 @@ def _handle_schema_update(args: argparse.Namespace, context: CliContext) -> dict
         profile=args.profile,
         app_key=args.app_key,
         record_id=args.record_id,
-        view_id=args.view_id,
     )
 
 
@@ -368,7 +309,6 @@ def _handle_list(args: argparse.Namespace, context: CliContext) -> dict:
         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"),
         page=args.page,
-        page_size=args.page_size,
         view_id=args.view_id,
     )
 
@@ -442,7 +382,6 @@ def _handle_update(args: argparse.Namespace, context: CliContext) -> dict:
             record_id=None,
             fields=None,
             items=require_list_arg(args.items_file, option_name="--items-file"),
-            view_id=args.view_id,
             dry_run=bool(args.dry_run),
             verify_write=bool(args.verify_write),
         )
@@ -461,29 +400,17 @@ def _handle_update(args: argparse.Namespace, context: CliContext) -> dict:
         app_key=args.app_key,
         record_id=args.record_id,
         fields=require_object_arg(args.fields_file, option_name="--fields-file"),
-        view_id=args.view_id,
         verify_write=bool(args.verify_write),
     )
 
 
 def _handle_delete(args: argparse.Namespace, context: CliContext) -> dict:
-    if args.legacy_list_type is not None:
-        raise_config_error(
-            "record delete no longer accepts list_type.",
-            fix_hint="Call `app_get` first and pass an accessible system `view_id`, for example `--view-id system:all`.",
-        )
-    if not (args.view_id or "").strip():
-        raise_config_error(
-            "record delete requires --view-id.",
-            fix_hint="Use a system view_id from app get accessible_views, for example `--view-id system:all`; custom views are not supported for deletion.",
-        )
     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,
-        view_id=args.view_id,
     )
 
 
@@ -519,7 +446,6 @@ def _handle_code_block_run(args: argparse.Namespace, context: CliContext) -> dic
         app_key=args.app_key,
         record_id=args.record_id,
         code_block_field=args.code_block_field,
-        view_id=args.view_id,
         role=args.role,
         workflow_node_id=args.workflow_node_id,
         answers=load_list_arg(args.answers_file, option_name="--answers-file"),

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

@@ -47,14 +47,20 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     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 必须来自 task list 的 data.items[].task_id")
-    get.add_argument("--task-id", help="来自 `qingflow --json task list` 的 data.items[].task_id；不是列表序号")
+    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", app_key="", record_id="", workflow_node_id=0)
+    get.set_defaults(handler=_handle_get, format_hint="task_get")
 
-    action = task_subparsers.add_parser("action", help="执行待办动作；--task-id 必须来自 task list 的 data.items[].task_id")
-    action.add_argument("--task-id", help="来自 `qingflow --json task list` 的 data.items[].task_id；不是列表序号")
+    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", help="不传时在交互终端中选择当前待办可执行动作")
     action.add_argument("--payload-file")
     action.add_argument("--fields-file")
@@ -62,27 +68,24 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
         handler=_handle_action,
         format_hint="task_action_execute",
         hide_effective_context_line=True,
-        app_key="",
-        record_id="",
-        workflow_node_id=0,
     )
 
-    report = task_subparsers.add_parser("report", help="读取待办关联报表详情；--task-id 必须来自 task list 的 data.items[].task_id")
-    report.add_argument("--task-id", help="来自 `qingflow --json task list` 的 data.items[].task_id；不是列表序号")
+    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", type=int, help="不传时在交互终端中选择关联报表")
     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",
-        app_key="",
-        record_id="",
-        workflow_node_id=0,
-    )
+    report.set_defaults(handler=_handle_report, format_hint="task_associated_report_detail_get")
 
-    log = task_subparsers.add_parser("log", help="读取流程日志；--task-id 必须来自 task list 的 data.items[].task_id")
-    log.add_argument("--task-id", help="来自 `qingflow --json task list` 的 data.items[].task_id；不是列表序号")
-    log.set_defaults(handler=_handle_log, format_hint="task_workflow_log_get", app_key="", record_id="", workflow_node_id=0)
+    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:
@@ -162,6 +165,9 @@ def _handle_action(args: argparse.Namespace, context: CliContext) -> dict:
     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=payload,
         fields=fields,
@@ -222,6 +228,9 @@ def _run_task_workbench_task_loop(args: argparse.Namespace, context: CliContext)
         result = 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=payload_selection,
             fields={},
@@ -234,20 +243,30 @@ def _run_task_workbench_task_loop(args: argparse.Namespace, context: CliContext)
 def _resolve_task_locator_or_select(args: argparse.Namespace, context: CliContext, *, tool_name: str) -> dict | None:
     if (args.task_id or "").strip():
         return None
+    has_app_key = bool((args.app_key or "").strip())
+    has_record_id = bool((args.record_id or "").strip())
+    has_workflow_node_id = int(args.workflow_node_id or 0) > 0
+    if has_app_key and has_record_id and has_workflow_node_id:
+        return None
+    if has_app_key or has_record_id or has_workflow_node_id:
+        raise_config_error(
+            f"{tool_name} requires --task-id, or --app-key together with --record-id and --workflow-node-id",
+            fix_hint="Either pass `--task-id TASK_ID`, or provide the full locator triple `--app-key --record-id --workflow-node-id`.",
+        )
 
     selection = _choose_todo_task_interactively(args, context, tool_name=tool_name)
     if selection.status == "unavailable":
         raise_config_error(
-            f"{tool_name} requires --task-id from task list data.items[].task_id",
+            f"{tool_name} requires --task-id, or --app-key together with --record-id and --workflow-node-id",
             fix_hint=(
                 "Retry in an interactive terminal to choose from current todo tasks, "
-                "or pass `--task-id` from `task list` explicitly."
+                "or pass `--task-id TASK_ID` explicitly."
             ),
         )
     if selection.status == "empty":
         raise_config_error(
             selection.message or f"{tool_name} could not open a selector because no current todo tasks are available.",
-            fix_hint="Run `task list` to confirm current todo tasks, then pass the selected `data.items[].task_id`.",
+            fix_hint="Run `task list` to confirm current todo tasks, or retry later with `--task-id TASK_ID`.",
         )
     if selection.status == "cancelled":
         return cancelled_result(selection.message or "已取消")
@@ -308,7 +327,7 @@ def _choose_todo_task_interactively(
         args,
         title=title,
         unavailable_message=(
-            f"{tool_name} requires --task-id from task list data.items[].task_id"
+            f"{tool_name} requires --task-id, or --app-key together with --record-id and --workflow-node-id"
         ),
         empty_message=f"{tool_name} could not open a selector because no current todo tasks are available.",
         load_options=load_options,
@@ -328,7 +347,7 @@ def _resolve_report_id_or_select(args: argparse.Namespace, context: CliContext)
     if selection.status == "empty":
         raise_config_error(
             selection.message or "task report could not open a selector because the selected task has no visible associated reports.",
-            fix_hint="Run `task get --task-id <data.items[].task_id>` to inspect `extras.associated_reports`, or choose another task.",
+            fix_hint="Run `task get --task-id TASK_ID` to inspect `extras.associated_reports`, or choose another task.",
         )
     if selection.status == "cancelled":
         return cancelled_result(selection.message or "已取消")
@@ -376,7 +395,7 @@ def _resolve_task_action_or_select(
     if selection.status == "empty":
         raise_config_error(
             selection.message or "task action could not open an action selector because no interactive actions are available.",
-            fix_hint="Run `task get --task-id <data.items[].task_id>` to inspect available_actions, or pass a supported `--action` explicitly.",
+            fix_hint="Run `task get --task-id TASK_ID` to inspect available_actions, or pass a supported `--action` explicitly.",
         )
     if selection.status == "cancelled":
         return cancelled_result(selection.message or "已取消")
@@ -457,7 +476,7 @@ def _resolve_action_payload_or_select(
         if selection.status == "empty":
             raise_config_error(
                 selection.message or "task rollback could not open a selector because no rollback candidates are visible.",
-                fix_hint="Run `task get --task-id <data.items[].task_id>` to inspect rollback candidates, or choose another action.",
+                fix_hint="Run `task get --task-id TASK_ID` to inspect rollback candidates, or choose another action.",
             )
         if selection.status == "cancelled":
             return cancelled_result(selection.message or "已取消")
@@ -474,7 +493,7 @@ def _resolve_action_payload_or_select(
         if selection.status == "empty":
             raise_config_error(
                 selection.message or "task transfer could not open a selector because no transfer candidates are visible.",
-                fix_hint="Run `task get --task-id <data.items[].task_id>` to inspect transfer candidates, or choose another action.",
+                fix_hint="Run `task get --task-id TASK_ID` to inspect transfer candidates, or choose another action.",
             )
         if selection.status == "cancelled":
             return cancelled_result(selection.message or "已取消")

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

@@ -11,7 +11,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
 
     get_parser = view_subparsers.add_parser("get", help="读取视图资源描述")
     get_parser.add_argument("--view-id", required=True)
-    get_parser.set_defaults(handler=_handle_get, format_hint="view_get")
+    get_parser.set_defaults(handler=_handle_get, format_hint="generic")
 
 
 def _handle_get(args: argparse.Namespace, context: CliContext) -> dict:

package/src/qingflow_mcp/cli/context.py

@@ -13,6 +13,7 @@ from ..tools.feedback_tools import FeedbackTools
 from ..tools.file_tools import FileTools
 from ..tools.import_tools import ImportTools
 from ..tools.record_tools import RecordTools
+from ..tools.repository_dev_tools import RepositoryDevTools
 from ..tools.resource_read_tools import ResourceReadTools
 from ..tools.task_context_tools import TaskContextTools
 from ..tools.workspace_tools import WorkspaceTools
@@ -34,6 +35,7 @@ class CliContext:
     files: FileTools
     builder_feedback: FeedbackTools
     builder: AiBuilderTools
+    repo: RepositoryDevTools
 
     def close(self) -> None:
         self.backend.close()
@@ -57,4 +59,5 @@ def build_cli_context() -> CliContext:
         files=FileTools(sessions, backend),
         builder_feedback=FeedbackTools(backend, mcp_side="App Builder MCP"),
         builder=AiBuilderTools(sessions, backend),
+        repo=RepositoryDevTools(sessions, backend),
     )