@josephyan/qingflow-cli 0.2.0-beta.81 → 0.2.0-beta.83

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -71,48 +71,36 @@ class AiBuilderTools(ToolBase):
         )
 
     def register(self, mcp) -> None:
-        @mcp.tool()
-        def package_list(profile: str = DEFAULT_PROFILE, trial_status: str = "all") -> JSONObject:
-            return self.package_list(profile=profile, trial_status=trial_status)
-
-        @mcp.tool()
-        def package_resolve(profile: str = DEFAULT_PROFILE, package_name: str = "") -> JSONObject:
-            return self.package_resolve(profile=profile, package_name=package_name)
-
         @mcp.tool()
         def builder_tool_contract(tool_name: str = "") -> JSONObject:
             return self.builder_tool_contract(tool_name=tool_name)
 
         @mcp.tool()
-        def package_create(
-            profile: str = DEFAULT_PROFILE,
-            package_name: str = "",
-            icon: str | None = None,
-            color: str | None = None,
-            visibility: JSONObject | None = None,
-        ) -> JSONObject:
-            return self.package_create(profile=profile, package_name=package_name, icon=icon, color=color, visibility=visibility)
+        def package_get(profile: str = DEFAULT_PROFILE, package_id: int = 0) -> JSONObject:
+            return self.package_get(profile=profile, package_id=package_id)
 
         @mcp.tool()
-        def package_get(profile: str = DEFAULT_PROFILE, tag_id: int = 0) -> JSONObject:
-            return self.package_get(profile=profile, tag_id=tag_id)
-
-        @mcp.tool()
-        def package_update(
+        def package_apply(
             profile: str = DEFAULT_PROFILE,
-            tag_id: int = 0,
+            package_id: int | None = None,
             package_name: str | None = None,
+            create_if_missing: bool = False,
             icon: str | None = None,
             color: str | None = None,
             visibility: JSONObject | None = None,
+            items: list[dict] | None = None,
+            allow_detach: bool = False,
         ) -> JSONObject:
-            return self.package_update(
+            return self.package_apply(
                 profile=profile,
-                tag_id=tag_id,
+                package_id=package_id,
                 package_name=package_name,
+                create_if_missing=create_if_missing,
                 icon=icon,
                 color=color,
                 visibility=visibility,
+                items=items or None,
+                allow_detach=allow_detach,
             )
 
         @mcp.tool()
@@ -172,14 +160,6 @@ class AiBuilderTools(ToolBase):
                 role_icon=role_icon,
             )
 
-        @mcp.tool()
-        def package_attach_app(
-            profile: str = DEFAULT_PROFILE,
-            tag_id: int = 0,
-            app_key: str = "",
-        ) -> JSONObject:
-            return self.package_attach_app(profile=profile, tag_id=tag_id, app_key=app_key)
-
         @mcp.tool()
         def app_release_edit_lock_if_mine(
             profile: str = DEFAULT_PROFILE,
@@ -199,24 +179,24 @@ class AiBuilderTools(ToolBase):
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
             app_name: str = "",
-            package_tag_id: int | None = None,
+            package_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):
+            has_package_id = package_id is not None
+            if has_app_key and (has_app_name or has_package_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`.",
+                    fix_hint="Use only `app_key`, or use `app_name` together with `package_id`.",
                 )
-            if not has_app_key and not (has_app_name and has_package_tag_id):
+            if not has_app_key and not (has_app_name and has_package_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`.",
+                    message="app_resolve requires either app_key, or app_name together with package_id.",
+                    fix_hint="For an existing known app, pass `app_key`. For package-scoped lookup, pass both `app_name` and `package_id`.",
                 )
-            return self.app_resolve(profile=profile, app_key=app_key, app_name=app_name, package_tag_id=package_tag_id)
+            return self.app_resolve(profile=profile, app_key=app_key, app_name=app_name, package_id=package_id)
 
         @mcp.tool()
         def app_custom_button_list(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
@@ -307,7 +287,7 @@ class AiBuilderTools(ToolBase):
         def app_schema_apply(
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
-            package_tag_id: int | None = None,
+            package_id: int | None = None,
             app_name: str = "",
             app_title: str = "",
             icon: str = "",
@@ -322,24 +302,24 @@ class AiBuilderTools(ToolBase):
             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
+            has_package_id = package_id is not None
             if has_app_key:
-                if create_if_missing or has_package_tag_id:
+                if create_if_missing or has_package_id:
                     return _config_failure(
                         tool_name="app_schema_apply",
                         message="app_schema_apply edit mode accepts app_key and optional app_name rename only.",
-                        fix_hint="For existing apps, use `app_key` and optionally `app_name`. For create mode, use `package_tag_id + app_name + create_if_missing=true`.",
+                        fix_hint="For existing apps, use `app_key` and optionally `app_name`. For create mode, use `package_id + app_name + create_if_missing=true`.",
                     )
-            elif not (create_if_missing and has_package_tag_id and (has_app_name or has_app_title)):
+            elif not (create_if_missing and has_package_id and (has_app_name or has_app_title)):
                 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.",
+                    message="app_schema_apply create mode requires package_id, app_name, and create_if_missing=true.",
+                    fix_hint="Use `app_key` for existing apps, or pass `package_id + app_name + create_if_missing=true` to create a new app.",
                 )
             return self.app_schema_apply(
                 profile=profile,
                 app_key=app_key,
-                package_tag_id=package_tag_id,
+                package_id=package_id,
                 app_name=app_name,
                 app_title=app_title,
                 icon=icon,
@@ -417,7 +397,7 @@ class AiBuilderTools(ToolBase):
             profile: str = DEFAULT_PROFILE,
             dash_key: str = "",
             dash_name: str = "",
-            package_tag_id: int | None = None,
+            package_id: int | None = None,
             publish: bool = True,
             sections: list[JSONObject] | None = None,
             visibility: JSONObject | None = None,
@@ -430,24 +410,24 @@ class AiBuilderTools(ToolBase):
         ) -> 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:
+            has_package_id = package_id is not None
+            if has_dash_key and has_package_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.",
+                    fix_hint="Use `dash_key` to update an existing portal, or use `package_id + dash_name` to create a new portal.",
                 )
-            if not has_dash_key and not (has_package_tag_id and has_dash_name):
+            if not has_dash_key and not (has_package_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`.",
+                    message="portal_apply requires either dash_key, or package_id together with dash_name.",
+                    fix_hint="Use `dash_key` for an existing portal. For create mode, pass `package_id + dash_name`.",
                 )
             return self.portal_apply(
                 profile=profile,
                 dash_key=dash_key,
                 dash_name=dash_name,
-                package_tag_id=package_tag_id,
+                package_id=package_id,
                 publish=publish,
                 sections=sections or [],
                 visibility=visibility,
@@ -463,12 +443,12 @@ class AiBuilderTools(ToolBase):
         def app_publish_verify(
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
-            expected_package_tag_id: int | None = None,
+            expected_package_id: int | None = None,
         ) -> JSONObject:
             return self.app_publish_verify(
                 profile=profile,
                 app_key=app_key,
-                expected_package_tag_id=expected_package_tag_id,
+                expected_package_id=expected_package_id,
             )
 
     def package_list(self, *, profile: str, trial_status: str = "all") -> JSONObject:
@@ -494,10 +474,10 @@ class AiBuilderTools(ToolBase):
         public_tool_names = public_builder_contract_tool_names()
         if requested in _PRIVATE_BUILDER_TOOL_CONTRACTS:
             lookup_name = ""
-        elif requested in _BUILDER_TOOL_CONTRACTS:
-            lookup_name = requested
         else:
             lookup_name = _BUILDER_TOOL_CONTRACT_ALIASES.get(requested, requested)
+            if lookup_name not in public_tool_names:
+                lookup_name = ""
         contract = _BUILDER_TOOL_CONTRACTS.get(lookup_name)
         if contract is None:
             return {
@@ -582,14 +562,60 @@ class AiBuilderTools(ToolBase):
             },
         )
 
-    def package_get(self, *, profile: str, tag_id: int) -> JSONObject:
-        normalized_args = {"tag_id": tag_id}
-        return _safe_tool_call(
-            lambda: self._facade.package_get(profile=profile, tag_id=tag_id),
+    def package_get(self, *, profile: str, package_id: int | None = None) -> JSONObject:
+        normalized_args = {"package_id": package_id}
+        return _publicize_package_fields(_safe_tool_call(
+            lambda: self._facade.package_get(profile=profile, package_id=package_id),
             error_code="PACKAGE_GET_FAILED",
             normalized_args=normalized_args,
-            suggested_next_call={"tool_name": "package_get", "arguments": {"profile": profile, "tag_id": tag_id}},
-        )
+            suggested_next_call={"tool_name": "package_get", "arguments": {"profile": profile, "package_id": package_id}},
+        ))
+
+    def package_apply(
+        self,
+        *,
+        profile: str,
+        package_id: int | None = None,
+        package_name: str | None = None,
+        create_if_missing: bool = False,
+        icon: str | None = None,
+        color: str | None = None,
+        visibility: JSONObject | None = None,
+        items: list[dict] | None = None,
+        allow_detach: bool = False,
+    ) -> JSONObject:
+        visibility_patch = None
+        if visibility is not None:
+            try:
+                visibility_patch = VisibilityPatch.model_validate(visibility)
+            except ValidationError as exc:
+                return _visibility_validation_failure(str(exc), tool_name="package_apply", exc=exc)
+        normalized_args = {
+            "package_id": package_id,
+            **({"package_name": package_name} if str(package_name or "").strip() else {}),
+            "create_if_missing": bool(create_if_missing),
+            **({"icon": icon} if icon else {}),
+            **({"color": color} if color else {}),
+            **({"visibility": visibility_patch.model_dump(mode="json")} if visibility_patch is not None else {}),
+            **({"items": deepcopy(items)} if items is not None else {}),
+            "allow_detach": bool(allow_detach),
+        }
+        return _publicize_package_fields(_safe_tool_call(
+            lambda: self._facade.package_apply(
+                profile=profile,
+                package_id=package_id,
+                package_name=package_name,
+                create_if_missing=create_if_missing,
+                icon=icon,
+                color=color,
+                visibility=visibility_patch,
+                items=items,
+                allow_detach=allow_detach,
+            ),
+            error_code="PACKAGE_APPLY_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "package_apply", "arguments": {"profile": profile, **normalized_args}},
+        ))
 
     def package_update(
         self,
@@ -765,14 +791,21 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_release_edit_lock_if_mine", "arguments": {"profile": profile, **normalized_args}},
         )
 
-    def app_resolve(self, *, profile: str, app_key: str = "", app_name: str = "", package_tag_id: int | None = None) -> JSONObject:
-        normalized_args = {"app_key": app_key, "app_name": app_name, "package_tag_id": package_tag_id}
-        return _safe_tool_call(
-            lambda: self._facade.app_resolve(profile=profile, app_key=app_key, app_name=app_name, package_tag_id=package_tag_id),
+    def app_resolve(
+        self,
+        *,
+        profile: str,
+        app_key: str = "",
+        app_name: str = "",
+        package_id: int | None = None,
+    ) -> JSONObject:
+        normalized_args = {"app_key": app_key, "app_name": app_name, "package_id": package_id}
+        return _publicize_package_fields(_safe_tool_call(
+            lambda: self._facade.app_resolve(profile=profile, app_key=app_key, app_name=app_name, package_tag_id=package_id),
             error_code="APP_RESOLVE_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "app_resolve", "arguments": {"profile": profile, **normalized_args}},
-        )
+        ))
 
     def app_custom_button_list(self, *, profile: str, app_key: str) -> JSONObject:
         normalized_args = {"app_key": app_key}
@@ -868,21 +901,21 @@ class AiBuilderTools(ToolBase):
 
     def app_read_summary(self, *, profile: str, app_key: str) -> JSONObject:
         normalized_args = {"app_key": app_key}
-        return _safe_tool_call(
+        return _publicize_package_fields(_safe_tool_call(
             lambda: self._facade.app_read_summary(profile=profile, app_key=app_key),
             error_code="APP_READ_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
-        )
+        ))
 
     def app_get(self, *, profile: str, app_key: str) -> JSONObject:
         normalized_args = {"app_key": app_key}
-        return _safe_tool_call(
+        return _publicize_package_fields(_safe_tool_call(
             lambda: self._facade.app_get(profile=profile, app_key=app_key),
             error_code="APP_GET_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
-        )
+        ))
 
     def app_read_fields(self, *, profile: str, app_key: str) -> JSONObject:
         normalized_args = {"app_key": app_key}
@@ -991,30 +1024,30 @@ class AiBuilderTools(ToolBase):
         )
 
     def portal_list(self, *, profile: str) -> JSONObject:
-        return _safe_tool_call(
+        return _publicize_package_fields(_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(
+        return _publicize_package_fields(_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(
+        return _publicize_package_fields(_safe_tool_call(
             lambda: self._facade.portal_read_summary(profile=profile, dash_key=dash_key, being_draft=being_draft),
             error_code="PORTAL_READ_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "portal_get", "arguments": {"profile": profile, **normalized_args}},
-        )
+        ))
 
     def view_get(self, *, profile: str, view_key: str = "", viewgraph_key: str = "") -> JSONObject:
         resolved_view_key = str(view_key or viewgraph_key or "").strip()
@@ -1045,7 +1078,7 @@ class AiBuilderTools(ToolBase):
         *,
         profile: str,
         app_key: str = "",
-        package_tag_id: int | None = None,
+        package_id: int | None = None,
         app_name: str = "",
         icon: str = "",
         color: str = "",
@@ -1059,7 +1092,7 @@ class AiBuilderTools(ToolBase):
             request = SchemaPlanRequest.model_validate(
                 {
                     "app_key": app_key,
-                    "package_tag_id": package_tag_id,
+                    "package_tag_id": package_id,
                     "app_name": app_name,
                     "icon": icon,
                     "color": color,
@@ -1080,7 +1113,7 @@ class AiBuilderTools(ToolBase):
                     "arguments": {
                         "profile": profile,
                         "app_key": app_key,
-                        "package_tag_id": package_tag_id,
+                        "package_id": package_id,
                         "app_name": app_name,
                         "icon": icon,
                         "color": color,
@@ -1092,12 +1125,13 @@ class AiBuilderTools(ToolBase):
                     },
                 },
             )
-        return _safe_tool_call(
+        normalized_args = _publicize_package_fields(request.model_dump(mode="json"))
+        return _publicize_package_fields(_safe_tool_call(
             lambda: self._facade.app_schema_plan(profile=profile, request=request),
             error_code="SCHEMA_PLAN_FAILED",
-            normalized_args=request.model_dump(mode="json"),
-            suggested_next_call={"tool_name": "app_schema_plan", "arguments": {"profile": profile, **request.model_dump(mode="json")}},
-        )
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_schema_plan", "arguments": {"profile": profile, **normalized_args}},
+        ))
 
     def app_layout_plan(
         self,
@@ -1235,7 +1269,7 @@ class AiBuilderTools(ToolBase):
         *,
         profile: str,
         app_key: str = "",
-        package_tag_id: int | None = None,
+        package_id: int | None = None,
         app_name: str = "",
         app_title: str = "",
         icon: str = "",
@@ -1250,7 +1284,7 @@ class AiBuilderTools(ToolBase):
         result = self._app_schema_apply_once(
             profile=profile,
             app_key=app_key,
-            package_tag_id=package_tag_id,
+            package_id=package_id,
             app_name=app_name,
             app_title=app_title,
             icon=icon,
@@ -1268,7 +1302,7 @@ class AiBuilderTools(ToolBase):
             retry_call=lambda: self._app_schema_apply_once(
                 profile=profile,
                 app_key=app_key,
-                package_tag_id=package_tag_id,
+                package_id=package_id,
                 app_name=app_name,
                 app_title=app_title,
                 icon=icon,
@@ -1287,7 +1321,7 @@ class AiBuilderTools(ToolBase):
         *,
         profile: str,
         app_key: str = "",
-        package_tag_id: int | None = None,
+        package_id: int | None = None,
         app_name: str = "",
         app_title: str = "",
         icon: str = "",
@@ -1304,7 +1338,7 @@ class AiBuilderTools(ToolBase):
             result=self.app_schema_plan(
                 profile=profile,
                 app_key=app_key,
-                package_tag_id=package_tag_id,
+                package_id=package_id,
                 app_name=effective_app_name,
                 icon=icon,
                 color=color,
@@ -1338,7 +1372,7 @@ class AiBuilderTools(ToolBase):
                     "arguments": {
                         "profile": profile,
                         "app_key": str(plan_args.get("app_key") or app_key),
-                        "package_tag_id": plan_args.get("package_tag_id", package_tag_id),
+                        "package_id": plan_args.get("package_id", package_id),
                         "app_name": str(plan_args.get("app_name") or effective_app_name),
                         "icon": str(plan_args.get("icon") or icon),
                         "color": str(plan_args.get("color") or color),
@@ -1353,7 +1387,7 @@ class AiBuilderTools(ToolBase):
             )
         normalized_args = {
             "app_key": str(plan_args.get("app_key") or app_key),
-            "package_tag_id": plan_args.get("package_tag_id", package_tag_id),
+            "package_id": plan_args.get("package_id", package_id),
             "app_name": str(plan_args.get("app_name") or effective_app_name),
             "icon": str(plan_args.get("icon") or icon or ""),
             "color": str(plan_args.get("color") or color or ""),
@@ -1368,7 +1402,7 @@ class AiBuilderTools(ToolBase):
             lambda: self._facade.app_schema_apply(
                 profile=profile,
                 app_key=str(plan_args.get("app_key") or app_key),
-                package_tag_id=plan_args.get("package_tag_id", package_tag_id),
+                package_tag_id=plan_args.get("package_id", package_id),
                 app_name=str(plan_args.get("app_name") or effective_app_name),
                 icon=str(plan_args.get("icon") or icon or ""),
                 color=str(plan_args.get("color") or color or ""),
@@ -1383,7 +1417,7 @@ class AiBuilderTools(ToolBase):
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "app_schema_apply", "arguments": {"profile": profile, **normalized_args}},
         )
-        return result
+        return _publicize_package_fields(result)
 
     def app_layout_apply(self, *, profile: str, app_key: str, mode: str = "merge", publish: bool = True, sections: list[JSONObject]) -> JSONObject:
         result = self._app_layout_apply_once(
@@ -1727,7 +1761,7 @@ class AiBuilderTools(ToolBase):
         profile: str,
         dash_key: str = "",
         dash_name: str = "",
-        package_tag_id: int | None = None,
+        package_id: int | None = None,
         publish: bool = True,
         sections: list[JSONObject],
         visibility: JSONObject | None = None,
@@ -1743,7 +1777,7 @@ class AiBuilderTools(ToolBase):
                 {
                     "dash_key": dash_key or None,
                     "dash_name": dash_name or None,
-                    "package_tag_id": package_tag_id,
+                    "package_tag_id": package_id,
                     "publish": publish,
                     "sections": sections or [],
                     "visibility": visibility,
@@ -1765,7 +1799,7 @@ class AiBuilderTools(ToolBase):
                     "arguments": {
                         "profile": profile,
                         "dash_name": dash_name or "业务门户",
-                        "package_tag_id": package_tag_id or 1001,
+                        "package_id": package_id or 1001,
                         "publish": True,
                         "sections": [
                             {
@@ -1778,30 +1812,37 @@ class AiBuilderTools(ToolBase):
                 },
             )
         normalized_args = request.model_dump(mode="json")
-        return _safe_tool_call(
+        normalized_args["package_id"] = normalized_args.pop("package_tag_id", package_id)
+        return _publicize_package_fields(_safe_tool_call(
             lambda: self._facade.portal_apply(profile=profile, request=request),
             error_code="PORTAL_APPLY_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "portal_apply", "arguments": {"profile": profile, **normalized_args}},
-        )
+        ))
 
-    def app_publish_verify(self, *, profile: str, app_key: str, expected_package_tag_id: int | None = None) -> JSONObject:
-        normalized_args = {"app_key": app_key, "expected_package_tag_id": expected_package_tag_id}
-        result = _safe_tool_call(
-            lambda: self._facade.app_publish_verify(profile=profile, app_key=app_key, expected_package_tag_id=expected_package_tag_id),
+    def app_publish_verify(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        expected_package_id: int | None = None,
+    ) -> JSONObject:
+        normalized_args = {"app_key": app_key, "expected_package_id": expected_package_id}
+        result = _publicize_package_fields(_safe_tool_call(
+            lambda: self._facade.app_publish_verify(profile=profile, app_key=app_key, expected_package_tag_id=expected_package_id),
             error_code="PUBLISH_VERIFY_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "app_publish_verify", "arguments": {"profile": profile, **normalized_args}},
-        )
-        return self._retry_after_self_lock_release(
+        ))
+        return _publicize_package_fields(self._retry_after_self_lock_release(
             profile=profile,
             result=result,
             retry_call=lambda: self._facade.app_publish_verify(
                 profile=profile,
                 app_key=app_key,
-                expected_package_tag_id=expected_package_tag_id,
+                expected_package_tag_id=expected_package_id,
             ),
-        )
+        ))
 
     def _retry_after_self_lock_release(self, *, profile: str, result: JSONObject, retry_call) -> JSONObject:
         if not isinstance(result, dict) or result.get("status") != "failed" or result.get("error_code") != "APP_EDIT_LOCKED":
@@ -2057,6 +2098,29 @@ def _safe_tool_call(
         }
 
 
+def _publicize_package_fields(value):
+    if isinstance(value, list):
+        return [_publicize_package_fields(item) for item in value]
+    if not isinstance(value, dict):
+        return value
+    key_map = {
+        "tag_id": "package_id",
+        "tag_ids": "package_ids",
+        "tag_ids_before": "package_ids_before",
+        "tag_ids_after": "package_ids_after",
+        "tag_name": "package_name",
+        "tag_icon": "icon",
+        "package_tag_id": "package_id",
+        "package_tag_ids": "package_ids",
+        "expected_package_tag_id": "expected_package_id",
+    }
+    public: JSONObject = {}
+    for key, item in value.items():
+        public_key = key_map.get(key, key)
+        public[public_key] = _publicize_package_fields(item)
+    return public
+
+
 def _coerce_api_error(error: Exception) -> QingflowApiError:
     if isinstance(error, QingflowApiError):
         return error
@@ -2205,88 +2269,59 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "tool_name": "chart_get",
         },
     },
-    "package_list": {
-        "allowed_keys": ["trial_status"],
-        "aliases": {"trialStatus": "trial_status"},
-        "allowed_values": {"trial_status": ["all", "trial", "formal"]},
-        "minimal_example": {
-            "profile": "default",
-            "trial_status": "all",
-        },
-    },
-    "package_resolve": {
-        "allowed_keys": ["package_name"],
-        "aliases": {"packageName": "package_name"},
-        "allowed_values": {},
-        "minimal_example": {
-            "profile": "default",
-            "package_name": "PLM（备用，施工中）",
-        },
-    },
-    "package_create": {
-        "allowed_keys": ["package_name", "icon", "color", "visibility"],
-        "aliases": {
-            "packageName": "package_name",
-            "iconName": "icon",
-            "iconColor": "color",
-        },
-        "allowed_values": deepcopy(_VISIBILITY_ALLOWED_VALUES),
-        "execution_notes": [
-            "create a package and optionally set visibility in the same call",
-            *_VISIBILITY_EXECUTION_NOTES,
-        ],
-        "minimal_example": {
-            "profile": "default",
-            "package_name": "项目管理",
-            "icon": "files-folder",
-            "color": "azure",
-            "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
-        },
-        "specific_visibility_example": {
-            "profile": "default",
-            "package_name": "项目管理",
-            "icon": "files-folder",
-            "color": "azure",
-            "visibility": deepcopy(_VISIBILITY_SPECIFIC_EXAMPLE),
-        },
-    },
     "package_get": {
-        "allowed_keys": ["tag_id"],
-        "aliases": {"tagId": "tag_id"},
+        "allowed_keys": ["package_id"],
+        "aliases": {"packageId": "package_id"},
         "allowed_values": {},
         "execution_notes": [
-            "returns package base info plus normalized visibility",
+            "returns complete public package schema with package_id, package_name, icon, visibility, and items",
+            "package_id maps internally to backend tagId; do not use tag_id in public calls",
             "visibility is normalized from backend MemberAuthInfoVO auth",
         ],
         "minimal_example": {
             "profile": "default",
-            "tag_id": 1001,
+            "package_id": 1001,
         },
     },
-    "package_update": {
-        "allowed_keys": ["tag_id", "package_name", "icon", "color", "visibility"],
+    "package_apply": {
+        "allowed_keys": ["package_id", "package_name", "create_if_missing", "icon", "color", "visibility", "items", "allow_detach"],
         "aliases": {
-            "tagId": "tag_id",
+            "packageId": "package_id",
             "packageName": "package_name",
+            "createIfMissing": "create_if_missing",
             "iconName": "icon",
             "iconColor": "color",
+            "allowDetach": "allow_detach",
         },
         "allowed_values": deepcopy(_VISIBILITY_ALLOWED_VALUES),
         "execution_notes": [
-            "update package name, icon, color, and/or visibility",
+            "create or update package metadata, visibility, grouping, and ordering in one call",
+            "package_id maps internally to backend tagId; do not use tag_id in public calls",
+            "items is a full package layout tree; omitting existing app/portal items is blocked unless allow_detach=true",
+            "item shapes: {type:'app', app_key}, {type:'portal', dash_key}, or {type:'group', group_id?, name, items:[...]}",
             *_VISIBILITY_EXECUTION_NOTES,
         ],
         "minimal_example": {
             "profile": "default",
-            "tag_id": 1001,
+            "package_id": 1001,
             "package_name": "项目管理",
             "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
+            "items": [{"type": "app", "app_key": "APP_KEY", "title": "项目台账"}],
+            "allow_detach": False,
         },
         "specific_visibility_example": {
             "profile": "default",
-            "tag_id": 1001,
+            "package_id": 1001,
             "visibility": deepcopy(_VISIBILITY_SPECIFIC_EXAMPLE),
         },
+        "create_example": {
+            "profile": "default",
+            "package_name": "项目管理",
+            "create_if_missing": True,
+            "icon": "files-folder",
+            "color": "azure",
+            "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
+        },
     },
     "solution_install": {
         "allowed_keys": ["solution_key", "being_copy_data", "solution_source"],
@@ -2350,28 +2385,14 @@ _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_keys": ["app_key", "app_name", "package_id"],
+        "aliases": {"packageId": "package_id"},
         "allowed_values": {},
         "execution_notes": [
             "use exactly one selector mode",
             "mode 1: app_key",
-            "mode 2: app_name + package_tag_id",
+            "mode 2: app_name + package_id",
         ],
         "minimal_example": {
             "profile": "default",
@@ -2380,7 +2401,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "package_scoped_example": {
             "profile": "default",
             "app_name": "研发项目管理",
-            "package_tag_id": 1001,
+            "package_id": 1001,
         },
     },
     "app_release_edit_lock_if_mine": {
@@ -2505,10 +2526,11 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_schema_plan": {
-        "allowed_keys": ["app_key", "package_tag_id", "app_name", "icon", "color", "visibility", "create_if_missing", "add_fields", "update_fields", "remove_fields"],
+        "allowed_keys": ["app_key", "package_id", "app_name", "icon", "color", "visibility", "create_if_missing", "add_fields", "update_fields", "remove_fields"],
         "aliases": {
             "app_title": "app_name",
             "title": "app_name",
+            "packageId": "package_id",
             "field.title": "field.name",
             "field.label": "field.name",
             "field.fields": "field.subfields",
@@ -2542,7 +2564,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "minimal_example": {
             "profile": "default",
             "app_name": "研发项目管理",
-            "package_tag_id": 1001,
+            "package_id": 1001,
             "icon": "template",
             "color": "emerald",
             "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
@@ -2569,10 +2591,11 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_schema_apply": {
-        "allowed_keys": ["app_key", "package_tag_id", "app_name", "icon", "color", "visibility", "create_if_missing", "publish", "add_fields", "update_fields", "remove_fields"],
+        "allowed_keys": ["app_key", "package_id", "app_name", "icon", "color", "visibility", "create_if_missing", "publish", "add_fields", "update_fields", "remove_fields"],
         "aliases": {
             "app_title": "app_name",
             "title": "app_name",
+            "packageId": "package_id",
             "field.title": "field.name",
             "field.label": "field.name",
             "field.fields": "field.subfields",
@@ -2605,7 +2628,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "execution_notes": [
             "use exactly one resource mode",
             "edit mode: app_key, optional app_name to rename the existing app",
-            "create mode: package_tag_id + app_name + create_if_missing=true",
+            "create mode: package_id + app_name + create_if_missing=true",
             "create mode defaults new app visibility to workspace/not when visibility is omitted; edit mode preserves current visibility when omitted",
             *_VISIBILITY_EXECUTION_NOTES,
             "multiple relation fields are backend-risky; read verification.relation_field_limit_verified and warnings before declaring the schema stable",
@@ -2624,7 +2647,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "minimal_example": {
             "profile": "default",
             "app_name": "研发项目管理",
-            "package_tag_id": 1001,
+            "package_id": 1001,
             "icon": "template",
             "color": "emerald",
             "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
@@ -3178,8 +3201,9 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "portal_apply": {
-        "allowed_keys": ["dash_key", "dash_name", "package_tag_id", "publish", "sections", "visibility", "auth", "icon", "color", "hide_copyright", "dash_global_config", "config"],
+        "allowed_keys": ["dash_key", "dash_name", "package_id", "publish", "sections", "visibility", "auth", "icon", "color", "hide_copyright", "dash_global_config", "config"],
         "aliases": {
+            "packageId": "package_id",
             "sourceType": "source_type",
             "chartRef": "chart_ref",
             "viewRef": "view_ref",
@@ -3196,10 +3220,10 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "execution_notes": [
             "use exactly one resource mode",
             "update mode: dash_key",
-            "create mode: package_tag_id + dash_name",
+            "create mode: package_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_id is required when creating a new portal",
             "publish=false only guarantees draft and base-info updates; it does not claim live has changed",
             "chart_ref resolves by chart_id first, then exact unique chart_name",
             "view_ref resolves by view_key first, then exact unique view_name",
@@ -3211,7 +3235,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "minimal_example": {
             "profile": "default",
             "dash_name": "经营门户",
-            "package_tag_id": 1001,
+            "package_id": 1001,
             "publish": True,
             "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
             "sections": [
@@ -3237,18 +3261,18 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_publish_verify": {
-        "allowed_keys": ["app_key", "expected_package_tag_id"],
+        "allowed_keys": ["app_key", "expected_package_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",
+            "expected_package_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,
+            "expected_package_id": 1001,
         },
     },
     "app_repair_code_blocks": {