@josephyan/qingflow-cli 0.2.0-beta.73 → 0.2.0-beta.75

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -6,6 +6,7 @@ import time
 
 from pydantic import ValidationError
 
+from ..public_surface import public_builder_contract_tool_names
 from ..config import DEFAULT_PROFILE
 from ..errors import QingflowApiError
 from ..json_types import JSONObject
@@ -90,6 +91,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 +231,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)
@@ -439,11 +463,7 @@ class AiBuilderTools(ToolBase):
 
     def builder_tool_contract(self, *, tool_name: str) -> JSONObject:
         requested = str(tool_name or "").strip()
-        public_tool_names = sorted(
-            name
-            for name in _BUILDER_TOOL_CONTRACTS.keys()
-            if name not in _PRIVATE_BUILDER_TOOL_CONTRACTS and name not in _BUILDER_TOOL_CONTRACT_ALIASES
-        )
+        public_tool_names = public_builder_contract_tool_names()
         if requested in _PRIVATE_BUILDER_TOOL_CONTRACTS:
             lookup_name = ""
         elif requested in _BUILDER_TOOL_CONTRACTS:
@@ -519,6 +539,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 +813,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 +1950,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",
@@ -1994,6 +2056,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": {},
@@ -2116,6 +2204,11 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "allowed_values": {
             "payload.trigger_action": [member.value for member in PublicButtonTriggerAction],
         },
+        "execution_notes": [
+            "custom button writes now auto-publish the current app draft as a fixed closing step",
+            "background_color and text_color cannot both be white",
+            "for addData buttons, put field mappings in payload.trigger_add_data_config.que_relation",
+        ],
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
@@ -2149,6 +2242,11 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "allowed_values": {
             "payload.trigger_action": [member.value for member in PublicButtonTriggerAction],
         },
+        "execution_notes": [
+            "custom button writes now auto-publish the current app draft as a fixed closing step",
+            "background_color and text_color cannot both be white",
+            "for addData buttons, put field mappings in payload.trigger_add_data_config.que_relation",
+        ],
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
@@ -2190,6 +2288,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "field.allow_multiple": "field.relation_mode",
             "field.optional_data_num": "field.relation_mode",
             "field.optionalDataNum": "field.relation_mode",
+            "field.departmentScope": "field.department_scope",
             "field.remoteLookupConfig": "field.remote_lookup_config",
             "field.qLinkerBinding": "field.q_linker_binding",
             "field.codeBlockConfig": "field.code_block_config",
@@ -2247,6 +2346,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "field.allow_multiple": "field.relation_mode",
             "field.optional_data_num": "field.relation_mode",
             "field.optionalDataNum": "field.relation_mode",
+            "field.departmentScope": "field.department_scope",
             "field.remoteLookupConfig": "field.remote_lookup_config",
             "field.qLinkerBinding": "field.q_linker_binding",
             "field.codeBlockConfig": "field.code_block_config",
@@ -2258,6 +2358,7 @@ _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.department_scope.mode": ["all", "custom"],
             "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()),
@@ -2269,10 +2370,14 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "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",
+            "relation fields now require both display_field and visible_fields in MCP/CLI payloads",
             "if relation target metadata lookup is blocked by 40161/40002/40027, explicit display_field.name and visible_fields[].name let builder degrade verification and still continue schema write",
+            "department fields accept department_scope with mode=all or mode=custom; custom scope requires explicit departments[].dept_id and optional include_sub_departs",
             "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": {
@@ -2304,6 +2409,24 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "update_fields": [],
             "remove_fields": [],
         },
+        "department_scope_example": {
+            "profile": "default",
+            "app_key": "APP_LEAD",
+            "publish": True,
+            "add_fields": [
+                {
+                    "name": "归属部门",
+                    "type": "department",
+                    "department_scope": {
+                        "mode": "custom",
+                        "departments": [{"dept_id": 334952, "dept_name": "生产"}],
+                        "include_sub_departs": False,
+                    },
+                }
+            ],
+            "update_fields": [],
+            "remove_fields": [],
+        },
         "code_block_example": {
             "profile": "default",
             "app_key": "APP_SCRIPT",
@@ -2858,6 +2981,23 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "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 = {