@josephyan/qingflow-cli 0.2.0-beta.72 → 0.2.0-beta.74

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -90,6 +90,20 @@ class AiBuilderTools(ToolBase):
         ) -> JSONObject:
             return self.package_create(profile=profile, package_name=package_name, icon=icon, color=color)
 
+        @mcp.tool()
+        def solution_install(
+            profile: str = DEFAULT_PROFILE,
+            solution_key: str = "",
+            being_copy_data: bool = True,
+            solution_source: str = "solutionDetail",
+        ) -> JSONObject:
+            return self.solution_install(
+                profile=profile,
+                solution_key=solution_key,
+                being_copy_data=being_copy_data,
+                solution_source=solution_source,
+            )
+
         @mcp.tool()
         def member_search(
             profile: str = DEFAULT_PROFILE,
@@ -216,6 +230,15 @@ class AiBuilderTools(ToolBase):
         def app_get_fields(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
             return self.app_get_fields(profile=profile, app_key=app_key)
 
+        @mcp.tool()
+        def app_repair_code_blocks(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            field: str | None = None,
+            apply: bool = False,
+        ) -> JSONObject:
+            return self.app_repair_code_blocks(profile=profile, app_key=app_key, field=field, apply=apply)
+
         @mcp.tool()
         def app_get_layout(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
             return self.app_get_layout(profile=profile, app_key=app_key)
@@ -519,6 +542,31 @@ class AiBuilderTools(ToolBase):
             },
         )
 
+    def solution_install(
+        self,
+        *,
+        profile: str,
+        solution_key: str,
+        being_copy_data: bool = True,
+        solution_source: str = "solutionDetail",
+    ) -> JSONObject:
+        normalized_args = {
+            "solution_key": solution_key,
+            "being_copy_data": being_copy_data,
+            "solution_source": solution_source,
+        }
+        return _safe_tool_call(
+            lambda: self._facade.solution_install(
+                profile=profile,
+                solution_key=solution_key,
+                being_copy_data=being_copy_data,
+                solution_source=solution_source,
+            ),
+            error_code="SOLUTION_INSTALL_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "solution_install", "arguments": {"profile": profile, **normalized_args}},
+        )
+
     def member_search(
         self,
         *,
@@ -768,6 +816,22 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_get_fields", "arguments": {"profile": profile, "app_key": app_key}},
         )
 
+    def app_repair_code_blocks(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        field: str | None = None,
+        apply: bool = False,
+    ) -> JSONObject:
+        normalized_args = {"app_key": app_key, "field": field, "apply": apply}
+        return _safe_tool_call(
+            lambda: self._facade.app_repair_code_blocks(profile=profile, app_key=app_key, field=field, apply=apply),
+            error_code="APP_REPAIR_CODE_BLOCKS_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_repair_code_blocks", "arguments": {"profile": profile, **normalized_args}},
+        )
+
     def app_read_layout_summary(self, *, profile: str, app_key: str) -> JSONObject:
         normalized_args = {"app_key": app_key}
         return _safe_tool_call(
@@ -1889,6 +1953,7 @@ def _public_error_message(error_code: str, error: QingflowApiError) -> str:
     mapping = {
         "PACKAGE_LIST_FAILED": "package list is unavailable in the current route",
         "PACKAGE_RESOLVE_FAILED": "package resolution is unavailable in the current route",
+        "SOLUTION_INSTALL_FAILED": "solution install could not complete because the app creation route or solution source is unavailable",
         "PACKAGE_ATTACH_FAILED": "package attachment could not be verified in the current route",
         "APP_RESOLVE_FAILED": "app resolution is unavailable in the current route",
         "CUSTOM_BUTTON_LIST_FAILED": "custom button list is unavailable in the current route",
@@ -1917,6 +1982,50 @@ def _public_error_message(error_code: str, error: QingflowApiError) -> str:
 
 
 _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
+    "file_upload_local": {
+        "allowed_keys": ["upload_kind", "file_path", "upload_mark", "content_type", "bucket_type", "path_id", "file_related_url"],
+        "aliases": {},
+        "allowed_values": {"upload_kind": ["attachment", "login"]},
+        "execution_notes": [
+            "returns upload metadata plus attachment-ready values for later builder or user writes",
+            "upload_kind=attachment may fall back to login upload info when the backend rejects attachment upload info",
+            "upload_mark is recommended for attachment uploads because it affects the remote storage path",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "upload_kind": "attachment",
+            "file_path": "/absolute/path/to/local-file.txt",
+            "upload_mark": "APP_KEY",
+        },
+    },
+    "feedback_submit": {
+        "allowed_keys": [
+            "category",
+            "title",
+            "description",
+            "expected_behavior",
+            "actual_behavior",
+            "impact_scope",
+            "tool_name",
+            "app_key",
+            "record_id",
+            "workflow_node_id",
+            "note",
+        ],
+        "aliases": {},
+        "allowed_values": {"category": ["bug", "missing_capability", "awkward_workflow", "ux", "docs"]},
+        "execution_notes": [
+            "submit feedback only after explicit user confirmation",
+            "use this when the current builder capability is unsupported or awkward after reasonable attempts",
+            "requires feedback qsource configuration but does not require Qingflow login or workspace selection",
+        ],
+        "minimal_example": {
+            "category": "missing_capability",
+            "title": "builder chart data read gap",
+            "description": "The current builder capability cannot satisfy the requested workflow.",
+            "tool_name": "chart_get",
+        },
+    },
     "package_list": {
         "allowed_keys": ["trial_status"],
         "aliases": {"trialStatus": "trial_status"},
@@ -1950,6 +2059,32 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "color": "azure",
         },
     },
+    "solution_install": {
+        "allowed_keys": ["solution_key", "being_copy_data", "solution_source"],
+        "aliases": {
+            "solutionKey": "solution_key",
+            "beingCopyData": "being_copy_data",
+            "copy_data": "being_copy_data",
+            "copyData": "being_copy_data",
+            "solutionSource": "solution_source",
+            "source": "solution_source",
+        },
+        "allowed_values": {
+            "being_copy_data": [True, False],
+            "solution_source": ["solutionDetail"],
+        },
+        "execution_notes": [
+            "solution_install calls the backend app creation route with a solutionKey payload",
+            "this is a write operation that may create multiple apps at once",
+            "app_keys are verified from the backend response when available",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "solution_key": "cfqrhth99401",
+            "being_copy_data": True,
+            "solution_source": "solutionDetail",
+        },
+    },
     "member_search": {
         "allowed_keys": ["query", "page_num", "page_size", "contain_disable"],
         "aliases": {},
@@ -2019,6 +2154,22 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "package_tag_id": 1001,
         },
     },
+    "app_release_edit_lock_if_mine": {
+        "allowed_keys": ["app_key", "lock_owner_email", "lock_owner_name"],
+        "aliases": {},
+        "allowed_values": {},
+        "execution_notes": [
+            "use this only after a builder write fails with APP_EDIT_LOCKED and the lock belongs to the current user",
+            "supply the lock owner details from the failed write result for a safe release attempt",
+            "after a successful release, retry the blocked builder write or publish verification call",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "lock_owner_email": "user@example.com",
+            "lock_owner_name": "当前用户",
+        },
+    },
     "app_custom_button_list": {
         "allowed_keys": ["app_key"],
         "aliases": {},
@@ -2213,6 +2364,8 @@ _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 outputs must be emitted through qf_output assignment; use qf_output = {...} or assign qf_output after building the result object, never const/let qf_output =",
+            "builder automatically normalizes const/let qf_output assignments on write and rejects output-bound code blocks that still do not contain a valid qf_output assignment",
             "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": {
@@ -2475,6 +2628,9 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "view.buttons.button_type": ["SYSTEM", "CUSTOM"],
             "view.buttons.config_type": ["TOP", "DETAIL"],
         },
+        "execution_notes": [
+            "for multi-value operators such as in, pass values as a list; value may also be used as an alias when it already contains a list",
+        ],
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
@@ -2534,6 +2690,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "read back app_get_views after any failed or partial view apply",
             "view existence verification and saved-filter verification are separate; treat filters as unverified until verification.view_filters_verified is true",
             "buttons omitted preserves existing button config; buttons=[] clears all buttons; buttons=[...] replaces the full button config",
+            "for multi-value operators such as in, pass values as a list; value may also be used as an alias when it already contains a list",
         ],
         "minimal_example": {
             "profile": "default",
@@ -2779,6 +2936,38 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             },
         },
     },
+    "app_publish_verify": {
+        "allowed_keys": ["app_key", "expected_package_tag_id"],
+        "aliases": {},
+        "allowed_values": {},
+        "execution_notes": [
+            "verifies that the current app draft has been published and is readable through the builder surface",
+            "expected_package_tag_id is optional and adds an extra package consistency check",
+            "when verification fails because of an edit lock owned by the current user, retry after app_release_edit_lock_if_mine",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "expected_package_tag_id": 1001,
+        },
+    },
+    "app_repair_code_blocks": {
+        "allowed_keys": ["app_key", "field", "apply"],
+        "aliases": {},
+        "allowed_values": {},
+        "execution_notes": [
+            "scan existing code_block fields for qf_output shadowing, missing output assignment, and broken writeback defaults",
+            "apply=false is a dry-run and returns a repair plan without writing builder config",
+            "apply=true rewrites only safe cases: const/let qf_output shadowing and stale relation-default output bindings reconstructed from readable code_block_binding config",
+            "this tool does not invent missing output aliases or guess missing target bindings when only low-level codeBlockConfig is present",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "field": "线索价值评估",
+            "apply": False,
+        },
+    },
 }
 
 _PRIVATE_BUILDER_TOOL_CONTRACTS = {