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

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -36,7 +36,7 @@ from ..builder_facade.models import (
     ViewsPreset,
     ViewsPlanRequest,
 )
-from ..builder_facade.service import AiBuilderFacade
+from ..builder_facade.service import AiBuilderFacade, INTEGRATION_OUTPUT_TARGET_FIELD_TYPES
 from .app_tools import AppTools
 from .base import ToolBase
 from .custom_button_tools import CustomButtonTools
@@ -138,9 +138,8 @@ class AiBuilderTools(ToolBase):
             profile: str = DEFAULT_PROFILE,
             tag_id: int = 0,
             app_key: str = "",
-            app_title: str = "",
         ) -> JSONObject:
-            return self.package_attach_app(profile=profile, tag_id=tag_id, app_key=app_key, app_title=app_title)
+            return self.package_attach_app(profile=profile, tag_id=tag_id, app_key=app_key)
 
         @mcp.tool()
         def app_release_edit_lock_if_mine(
@@ -163,6 +162,21 @@ class AiBuilderTools(ToolBase):
             app_name: str = "",
             package_tag_id: int | None = None,
         ) -> JSONObject:
+            has_app_key = bool((app_key or "").strip())
+            has_app_name = bool((app_name or "").strip())
+            has_package_tag_id = package_tag_id is not None
+            if has_app_key and (has_app_name or has_package_tag_id):
+                return _config_failure(
+                    tool_name="app_resolve",
+                    message="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):
+                return _config_failure(
+                    tool_name="app_resolve",
+                    message="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 self.app_resolve(profile=profile, app_key=app_key, app_name=app_name, package_tag_id=package_tag_id)
 
         @mcp.tool()
@@ -218,6 +232,18 @@ class AiBuilderTools(ToolBase):
         def app_read_charts_summary(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
             return self.app_read_charts_summary(profile=profile, app_key=app_key)
 
+        @mcp.tool()
+        def portal_list(profile: str = DEFAULT_PROFILE) -> JSONObject:
+            return self.portal_list(profile=profile)
+
+        @mcp.tool()
+        def portal_get(
+            profile: str = DEFAULT_PROFILE,
+            dash_key: str = "",
+            being_draft: bool = True,
+        ) -> JSONObject:
+            return self.portal_get(profile=profile, dash_key=dash_key, being_draft=being_draft)
+
         @mcp.tool()
         def portal_read_summary(
             profile: str = DEFAULT_PROFILE,
@@ -226,6 +252,30 @@ class AiBuilderTools(ToolBase):
         ) -> JSONObject:
             return self.portal_read_summary(profile=profile, dash_key=dash_key, being_draft=being_draft)
 
+        @mcp.tool()
+        def view_get(profile: str = DEFAULT_PROFILE, viewgraph_key: str = "") -> JSONObject:
+            return self.view_get(profile=profile, viewgraph_key=viewgraph_key)
+
+        @mcp.tool()
+        def chart_get(
+            profile: str = DEFAULT_PROFILE,
+            chart_id: str = "",
+            data_payload: JSONObject | None = None,
+            page_num: int | None = None,
+            page_size: int | None = None,
+            page_num_y: int | None = None,
+            page_size_y: int | None = None,
+        ) -> JSONObject:
+            return self.chart_get(
+                profile=profile,
+                chart_id=chart_id,
+                data_payload=data_payload or {},
+                page_num=page_num,
+                page_size=page_size,
+                page_num_y=page_num_y,
+                page_size_y=page_size_y,
+            )
+
         @mcp.tool()
         def app_schema_apply(
             profile: str = DEFAULT_PROFILE,
@@ -241,6 +291,23 @@ class AiBuilderTools(ToolBase):
             update_fields: list[JSONObject] | None = None,
             remove_fields: list[JSONObject] | None = None,
         ) -> JSONObject:
+            has_app_key = bool((app_key or "").strip())
+            has_app_name = bool((app_name or "").strip())
+            has_app_title = bool((app_title or "").strip())
+            has_package_tag_id = package_tag_id is not None
+            if has_app_key:
+                if create_if_missing or has_app_name or has_package_tag_id or has_app_title:
+                    return _config_failure(
+                        tool_name="app_schema_apply",
+                        message="app_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=true`.",
+                    )
+            elif not (create_if_missing and has_package_tag_id and has_app_name):
+                return _config_failure(
+                    tool_name="app_schema_apply",
+                    message="app_schema_apply create mode requires package_tag_id, app_name, and create_if_missing=true.",
+                    fix_hint="Use `app_key` for existing apps, or pass `package_tag_id + app_name + create_if_missing=true` to create a new app.",
+                )
             return self.app_schema_apply(
                 profile=profile,
                 app_key=app_key,
@@ -331,6 +398,21 @@ class AiBuilderTools(ToolBase):
             dash_global_config: JSONObject | None = None,
             config: JSONObject | None = None,
         ) -> JSONObject:
+            has_dash_key = bool((dash_key or "").strip())
+            has_dash_name = bool((dash_name or "").strip())
+            has_package_tag_id = package_tag_id is not None
+            if has_dash_key and has_package_tag_id:
+                return _config_failure(
+                    tool_name="portal_apply",
+                    message="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):
+                return _config_failure(
+                    tool_name="portal_apply",
+                    message="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 self.portal_apply(
                 profile=profile,
                 dash_key=dash_key,
@@ -725,6 +807,23 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_read_charts_summary", "arguments": {"profile": profile, "app_key": app_key}},
         )
 
+    def portal_list(self, *, profile: str) -> JSONObject:
+        return _safe_tool_call(
+            lambda: self._facade.portal_list(profile=profile),
+            error_code="PORTAL_LIST_FAILED",
+            normalized_args={},
+            suggested_next_call={"tool_name": "portal_list", "arguments": {"profile": profile}},
+        )
+
+    def portal_get(self, *, profile: str, dash_key: str, being_draft: bool = True) -> JSONObject:
+        normalized_args = {"dash_key": dash_key, "being_draft": being_draft}
+        return _safe_tool_call(
+            lambda: self._facade.portal_get(profile=profile, dash_key=dash_key, being_draft=being_draft),
+            error_code="PORTAL_GET_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "portal_get", "arguments": {"profile": profile, **normalized_args}},
+        )
+
     def portal_read_summary(self, *, profile: str, dash_key: str, being_draft: bool = True) -> JSONObject:
         normalized_args = {"dash_key": dash_key, "being_draft": being_draft}
         return _safe_tool_call(
@@ -734,6 +833,49 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "portal_read_summary", "arguments": {"profile": profile, **normalized_args}},
         )
 
+    def view_get(self, *, profile: str, viewgraph_key: str) -> JSONObject:
+        normalized_args = {"viewgraph_key": viewgraph_key}
+        return _safe_tool_call(
+            lambda: self._facade.view_get(profile=profile, viewgraph_key=viewgraph_key),
+            error_code="VIEW_GET_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "view_get", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    def chart_get(
+        self,
+        *,
+        profile: str,
+        chart_id: str,
+        data_payload: JSONObject | None = None,
+        page_num: int | None = None,
+        page_size: int | None = None,
+        page_num_y: int | None = None,
+        page_size_y: int | None = None,
+    ) -> JSONObject:
+        normalized_args = {
+            "chart_id": chart_id,
+            "data_payload": deepcopy(data_payload) if isinstance(data_payload, dict) else {},
+            "page_num": page_num,
+            "page_size": page_size,
+            "page_num_y": page_num_y,
+            "page_size_y": page_size_y,
+        }
+        return _safe_tool_call(
+            lambda: self._facade.chart_get(
+                profile=profile,
+                chart_id=chart_id,
+                data_payload=normalized_args["data_payload"],
+                page_num=page_num,
+                page_size=page_size,
+                page_num_y=page_num_y,
+                page_size_y=page_size_y,
+            ),
+            error_code="CHART_GET_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "chart_get", "arguments": {"profile": profile, "chart_id": chart_id}},
+        )
+
     def app_schema_plan(
         self,
         *,
@@ -1645,6 +1787,29 @@ def _validation_failure(
     }
 
 
+def _config_failure(*, tool_name: str, message: str, fix_hint: str) -> JSONObject:
+    contract = _BUILDER_TOOL_CONTRACTS.get(tool_name or "")
+    return {
+        "status": "failed",
+        "error_code": "CONFIG_ERROR",
+        "recoverable": True,
+        "message": message,
+        "normalized_args": {},
+        "missing_fields": [],
+        "allowed_values": deepcopy(contract.get("allowed_values", {})) if isinstance(contract, dict) else {},
+        "details": {
+            "fix_hint": fix_hint,
+            "allowed_keys": deepcopy(contract.get("allowed_keys", [])) if isinstance(contract, dict) else [],
+        },
+        "suggested_next_call": None,
+        "request_id": None,
+        "backend_code": None,
+        "http_status": None,
+        "noop": False,
+        "verification": {},
+    }
+
+
 def _safe_tool_call(
     call,
     *,
@@ -1807,6 +1972,39 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "role_icon": "ex-user-outlined",
         },
     },
+    "package_attach_app": {
+        "allowed_keys": ["tag_id", "app_key"],
+        "aliases": {},
+        "allowed_values": {},
+        "execution_notes": [
+            "attach one existing app to one existing package",
+            "app_title is no longer accepted as a public selector; resolve the app first and pass app_key",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "tag_id": 1001,
+            "app_key": "APP_KEY",
+        },
+    },
+    "app_resolve": {
+        "allowed_keys": ["app_key", "app_name", "package_tag_id"],
+        "aliases": {},
+        "allowed_values": {},
+        "execution_notes": [
+            "use exactly one selector mode",
+            "mode 1: app_key",
+            "mode 2: app_name + package_tag_id",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+        },
+        "package_scoped_example": {
+            "profile": "default",
+            "app_name": "研发项目管理",
+            "package_tag_id": 1001,
+        },
+    },
     "app_custom_button_list": {
         "allowed_keys": ["app_key"],
         "aliases": {},
@@ -1986,9 +2184,14 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "allowed_values": {
             "field.type": [member.value for member in PublicFieldType],
             "field.relation_mode": [member.value for member in PublicRelationMode],
+            "field.code_block_binding.outputs.target_field.type": list(INTEGRATION_OUTPUT_TARGET_FIELD_TYPES),
+            "field.q_linker_binding.outputs.target_field.type": list(INTEGRATION_OUTPUT_TARGET_FIELD_TYPES),
             "field_type_ids": sorted(FIELD_TYPE_ID_ALIASES.keys()),
         },
         "execution_notes": [
+            "use exactly one resource mode",
+            "edit mode: app_key",
+            "create mode: package_tag_id + app_name + create_if_missing=true",
             "multiple relation fields are backend-risky; read verification.relation_field_limit_verified and warnings before declaring the schema stable",
             "backend 49614 is normalized to MULTIPLE_RELATION_FIELDS_UNSUPPORTED with a workaround message",
             "relation_mode=multiple maps to referenceConfig.optionalDataNum=0",
@@ -1996,6 +2199,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "q_linker_binding lets you declare request config, dynamic inputs, alias parsing, and target-field bindings in one step; builder writes remoteLookupConfig plus the existing backend relation-default and questionRelations structures",
             "code_block_binding lets you declare inputs, code, alias parsing, and target-field bindings in one step; builder writes codeBlockConfig plus the existing backend relation-default and questionRelations structures",
             "builder configures code blocks only; it does not execute or trigger code blocks",
+            "code_block_binding and q_linker_binding target fields are limited to text, long_text, number, amount, date, datetime, single_select, multi_select, and boolean",
         ],
         "minimal_example": {
             "profile": "default",
@@ -2031,6 +2235,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "app_key": "APP_SCRIPT",
             "publish": True,
             "add_fields": [
+                {"name": "客户等级", "type": "text"},
                 {
                     "name": "查询代码块",
                     "type": "code_block",
@@ -2039,12 +2244,12 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
                             {"field": {"name": "客户名称"}, "var": "customerName"},
                             {"field": {"name": "预算金额"}, "var": "budget"},
                         ],
-                        "code": "const qf_output = {}; qf_output.customerLevel = budget > 100000 ? 'A' : 'B'; return qf_output;",
+                        "code": "qf_output = {}; qf_output.customerLevel = budget > 100000 ? 'A' : 'B';",
                         "auto_trigger": True,
                         "custom_button_text_enabled": True,
                         "custom_button_text": "评估客户",
                         "outputs": [
-                            {"alias": "customerLevel", "path": "$.customerLevel"},
+                            {"alias": "customerLevel", "path": "$.customerLevel", "target_field": {"name": "客户等级"}},
                         ],
                     },
                 }
@@ -2355,6 +2560,34 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "app_key": "APP_KEY",
         },
     },
+    "portal_list": {
+        "allowed_keys": [],
+        "aliases": {},
+        "allowed_values": {},
+        "execution_notes": [
+            "returns the current user's accessible portal list",
+            "use this as the portal discovery path before portal_get",
+            "results are compact list items, not raw dash payloads",
+        ],
+        "minimal_example": {
+            "profile": "default",
+        },
+    },
+    "portal_get": {
+        "allowed_keys": ["dash_key", "being_draft"],
+        "aliases": {"beingDraft": "being_draft"},
+        "allowed_values": {},
+        "execution_notes": [
+            "returns portal-level detail plus a component inventory",
+            "chart and view components are returned as refs only; use chart_get or view_get for more detail",
+            "being_draft=true reads the current draft view; being_draft=false reads live",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "dash_key": "DASH_KEY",
+            "being_draft": True,
+        },
+    },
     "app_charts_apply": {
         "allowed_keys": ["app_key", "upsert_charts", "remove_chart_ids", "reorder_chart_ids"],
         "aliases": {
@@ -2419,6 +2652,35 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "being_draft": True,
         },
     },
+    "view_get": {
+        "allowed_keys": ["viewgraph_key"],
+        "aliases": {"viewKey": "viewgraph_key"},
+        "allowed_values": {},
+        "execution_notes": [
+            "returns one view's definition detail",
+            "does not return record data; use record_list with app_key + view_id for rows",
+            "use this after portal_get when a component references a view_ref.view_key",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "viewgraph_key": "VIEW_KEY",
+        },
+    },
+    "chart_get": {
+        "allowed_keys": ["chart_id", "data_payload", "page_num", "page_size", "page_num_y", "page_size_y"],
+        "aliases": {"payload": "data_payload"},
+        "allowed_values": {},
+        "execution_notes": [
+            "returns chart base info, chart config, and chart data together",
+            "chart_id is required; chart names are not accepted here",
+            "data_payload defaults to {} so chart_get queries concrete chart data by default",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "chart_id": "CHART_ID",
+            "data_payload": {},
+        },
+    },
     "portal_apply": {
         "allowed_keys": ["dash_key", "dash_name", "package_tag_id", "publish", "sections", "auth", "icon", "color", "hide_copyright", "dash_global_config", "config"],
         "aliases": {
@@ -2436,6 +2698,9 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
         "allowed_values": {"section.source_type": ["chart", "view", "grid", "filter", "text", "link"]},
         "execution_notes": [
+            "use exactly one resource mode",
+            "update mode: dash_key",
+            "create mode: package_tag_id + dash_name",
             "portal_apply uses replace semantics for sections",
             "remove a section by omitting it from the new sections list",
             "package_tag_id is required when creating a new portal",

package/src/qingflow_mcp/tools/app_tools.py

@@ -179,6 +179,8 @@ class AppTools(ToolBase):
             accessible_views.extend(self._resolve_accessible_custom_views(context, app_key))
             import_capability, import_warnings = _derive_import_capability(base_info)
             warnings.extend(import_warnings)
+            editability, editability_warnings = _derive_editability(base_info)
+            warnings.extend(editability_warnings)
 
             return {
                 "profile": profile,
@@ -191,6 +193,7 @@ class AppTools(ToolBase):
                     "app_name": app_name,
                     "can_create": can_create,
                     "import_capability": import_capability,
+                    "editability": editability,
                     "accessible_views": accessible_views,
                 },
             }
@@ -836,6 +839,32 @@ def _unknown_import_capability(
     }
 
 
+def _derive_editability(base_info: Any) -> tuple[JSONObject, list[JSONObject]]:
+    warnings: list[JSONObject] = []
+    if not isinstance(base_info, dict):
+        warnings.append(
+            {
+                "code": "APP_EDITABILITY_UNAVAILABLE",
+                "message": "app_get could not determine editability because baseInfo was unavailable.",
+            }
+        )
+        return {
+            "can_edit_form": None,
+            "can_edit_flow": None,
+            "can_edit_views": None,
+            "can_edit_charts": None,
+        }, warnings
+
+    edit_item_status = _coerce_optional_bool(base_info.get("editItemStatus"))
+    data_manage_status = _coerce_optional_bool(base_info.get("dataManageStatus"))
+    return {
+        "can_edit_form": edit_item_status,
+        "can_edit_flow": edit_item_status,
+        "can_edit_views": data_manage_status,
+        "can_edit_charts": data_manage_status,
+    }, warnings
+
+
 def _coerce_positive_int(value: Any) -> int | None:
     try:
         number = int(value)