@josephyan/qingflow-cli 0.2.0-beta.78 → 0.2.0-beta.80

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -32,6 +32,7 @@ from ..builder_facade.models import (
     PublicChartType,
     PublicViewType,
     SchemaPlanRequest,
+    VisibilityPatch,
     ViewFilterOperator,
     ViewUpsertPatch,
     ViewsPreset,
@@ -88,8 +89,31 @@ class AiBuilderTools(ToolBase):
             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)
+            return self.package_create(profile=profile, package_name=package_name, icon=icon, color=color, visibility=visibility)
+
+        @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(
+            profile: str = DEFAULT_PROFILE,
+            tag_id: int = 0,
+            package_name: str | None = None,
+            icon: str | None = None,
+            color: str | None = None,
+            visibility: JSONObject | None = None,
+        ) -> JSONObject:
+            return self.package_update(
+                profile=profile,
+                tag_id=tag_id,
+                package_name=package_name,
+                icon=icon,
+                color=color,
+                visibility=visibility,
+            )
 
         @mcp.tool()
         def solution_install(
@@ -288,6 +312,7 @@ class AiBuilderTools(ToolBase):
             app_title: str = "",
             icon: str = "",
             color: str = "",
+            visibility: JSONObject | None = None,
             create_if_missing: bool = False,
             publish: bool = True,
             add_fields: list[JSONObject] | None = None,
@@ -319,6 +344,7 @@ class AiBuilderTools(ToolBase):
                 app_title=app_title,
                 icon=icon,
                 color=color,
+                visibility=visibility,
                 create_if_missing=create_if_missing,
                 publish=publish,
                 add_fields=add_fields or [],
@@ -394,6 +420,7 @@ class AiBuilderTools(ToolBase):
             package_tag_id: int | None = None,
             publish: bool = True,
             sections: list[JSONObject] | None = None,
+            visibility: JSONObject | None = None,
             auth: JSONObject | None = None,
             icon: str | None = None,
             color: str | None = None,
@@ -423,6 +450,7 @@ class AiBuilderTools(ToolBase):
                 package_tag_id=package_tag_id,
                 publish=publish,
                 sections=sections or [],
+                visibility=visibility,
                 auth=auth,
                 icon=icon,
                 color=color,
@@ -518,14 +546,28 @@ class AiBuilderTools(ToolBase):
         package_name: str,
         icon: str | None = None,
         color: str | None = None,
+        visibility: JSONObject | None = None,
     ) -> 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_create", exc=exc)
         normalized_args = {
             "package_name": package_name,
             **({"icon": icon} if icon else {}),
             **({"color": color} if color else {}),
+            **({"visibility": visibility_patch.model_dump(mode="json")} if visibility_patch is not None else {}),
         }
         return _safe_tool_call(
-            lambda: self._facade.package_create(profile=profile, package_name=package_name, icon=icon, color=color),
+            lambda: self._facade.package_create(
+                profile=profile,
+                package_name=package_name,
+                icon=icon,
+                color=color,
+                visibility=visibility_patch,
+            ),
             error_code="PACKAGE_CREATE_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={
@@ -535,10 +577,57 @@ class AiBuilderTools(ToolBase):
                     "package_name": package_name,
                     **({"icon": icon} if icon else {}),
                     **({"color": color} if color else {}),
+                    **({"visibility": visibility_patch.model_dump(mode="json")} if visibility_patch is not None else {}),
                 },
             },
         )
 
+    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),
+            error_code="PACKAGE_GET_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "package_get", "arguments": {"profile": profile, "tag_id": tag_id}},
+        )
+
+    def package_update(
+        self,
+        *,
+        profile: str,
+        tag_id: int,
+        package_name: str | None = None,
+        icon: str | None = None,
+        color: str | None = None,
+        visibility: JSONObject | None = None,
+    ) -> 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_update", exc=exc)
+        normalized_args = {
+            "tag_id": tag_id,
+            **({"package_name": package_name} if str(package_name or "").strip() else {}),
+            **({"icon": icon} if icon else {}),
+            **({"color": color} if color else {}),
+            **({"visibility": visibility_patch.model_dump(mode="json")} if visibility_patch is not None else {}),
+        }
+        return _safe_tool_call(
+            lambda: self._facade.package_update(
+                profile=profile,
+                tag_id=tag_id,
+                package_name=package_name,
+                icon=icon,
+                color=color,
+                visibility=visibility_patch,
+            ),
+            error_code="PACKAGE_UPDATE_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "package_update", "arguments": {"profile": profile, **normalized_args}},
+        )
+
     def solution_install(
         self,
         *,
@@ -960,6 +1049,7 @@ class AiBuilderTools(ToolBase):
         app_name: str = "",
         icon: str = "",
         color: str = "",
+        visibility: JSONObject | None = None,
         create_if_missing: bool = False,
         add_fields: list[JSONObject],
         update_fields: list[JSONObject],
@@ -973,6 +1063,7 @@ class AiBuilderTools(ToolBase):
                     "app_name": app_name,
                     "icon": icon,
                     "color": color,
+                    "visibility": visibility,
                     "create_if_missing": create_if_missing,
                     "add_fields": add_fields,
                     "update_fields": update_fields,
@@ -980,7 +1071,7 @@ class AiBuilderTools(ToolBase):
                 }
             )
         except ValidationError as exc:
-            return _validation_failure(
+            return _visibility_validation_failure(
                 str(exc),
                 tool_name="app_schema_plan",
                 exc=exc,
@@ -993,6 +1084,7 @@ class AiBuilderTools(ToolBase):
                         "app_name": app_name,
                         "icon": icon,
                         "color": color,
+                        "visibility": visibility,
                         "create_if_missing": create_if_missing,
                         "add_fields": [{"name": "字段名称", "type": "text"}],
                         "update_fields": [],
@@ -1116,7 +1208,7 @@ class AiBuilderTools(ToolBase):
                 }
             )
         except ValidationError as exc:
-            return _validation_failure(
+            return _visibility_validation_failure(
                 str(exc),
                 tool_name="app_views_plan",
                 exc=exc,
@@ -1148,6 +1240,7 @@ class AiBuilderTools(ToolBase):
         app_title: str = "",
         icon: str = "",
         color: str = "",
+        visibility: JSONObject | None = None,
         create_if_missing: bool = False,
         publish: bool = True,
         add_fields: list[JSONObject],
@@ -1162,6 +1255,7 @@ class AiBuilderTools(ToolBase):
             app_title=app_title,
             icon=icon,
             color=color,
+            visibility=visibility,
             create_if_missing=create_if_missing,
             publish=publish,
             add_fields=add_fields,
@@ -1179,6 +1273,7 @@ class AiBuilderTools(ToolBase):
                 app_title=app_title,
                 icon=icon,
                 color=color,
+                visibility=visibility,
                 create_if_missing=create_if_missing,
                 publish=publish,
                 add_fields=add_fields,
@@ -1197,6 +1292,7 @@ class AiBuilderTools(ToolBase):
         app_title: str = "",
         icon: str = "",
         color: str = "",
+        visibility: JSONObject | None = None,
         create_if_missing: bool = False,
         publish: bool = True,
         add_fields: list[JSONObject],
@@ -1212,6 +1308,7 @@ class AiBuilderTools(ToolBase):
                 app_name=effective_app_name,
                 icon=icon,
                 color=color,
+                visibility=visibility,
                 create_if_missing=create_if_missing,
                 add_fields=add_fields,
                 update_fields=update_fields,
@@ -1245,6 +1342,7 @@ class AiBuilderTools(ToolBase):
                         "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),
+                        "visibility": plan_args.get("visibility") or visibility,
                         "create_if_missing": bool(plan_args.get("create_if_missing", create_if_missing)),
                         "publish": publish,
                         "add_fields": plan_args.get("add_fields") or [{"name": "字段名称", "type": "text", "required": False}],
@@ -1259,6 +1357,7 @@ class AiBuilderTools(ToolBase):
             "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 ""),
+            "visibility": plan_args.get("visibility") or visibility,
             "create_if_missing": bool(plan_args.get("create_if_missing", create_if_missing)),
             "publish": publish,
             "add_fields": [patch.model_dump(mode="json") for patch in parsed_add],
@@ -1273,6 +1372,7 @@ class AiBuilderTools(ToolBase):
                 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 ""),
+                visibility=VisibilityPatch.model_validate(plan_args.get("visibility")) if plan_args.get("visibility") is not None else None,
                 create_if_missing=bool(plan_args.get("create_if_missing", create_if_missing)),
                 publish=publish,
                 add_fields=parsed_add,
@@ -1528,7 +1628,7 @@ class AiBuilderTools(ToolBase):
         try:
             parsed_views = [ViewUpsertPatch.model_validate(item) for item in plan_args.get("upsert_views") or []]
         except ValidationError as exc:
-            return _validation_failure(
+            return _visibility_validation_failure(
                 str(exc),
                 tool_name="app_views_apply",
                 exc=exc,
@@ -1598,7 +1698,7 @@ class AiBuilderTools(ToolBase):
                 }
             )
         except ValidationError as exc:
-            return _validation_failure(
+            return _visibility_validation_failure(
                 str(exc),
                 tool_name="app_charts_apply",
                 exc=exc,
@@ -1630,6 +1730,7 @@ class AiBuilderTools(ToolBase):
         package_tag_id: int | None = None,
         publish: bool = True,
         sections: list[JSONObject],
+        visibility: JSONObject | None = None,
         auth: JSONObject | None = None,
         icon: str | None = None,
         color: str | None = None,
@@ -1645,6 +1746,7 @@ class AiBuilderTools(ToolBase):
                     "package_tag_id": package_tag_id,
                     "publish": publish,
                     "sections": sections or [],
+                    "visibility": visibility,
                     "auth": auth,
                     "icon": icon,
                     "color": color,
@@ -1654,7 +1756,7 @@ class AiBuilderTools(ToolBase):
                 }
             )
         except ValidationError as exc:
-            return _validation_failure(
+            return _visibility_validation_failure(
                 str(exc),
                 tool_name="portal_apply",
                 exc=exc,
@@ -1862,6 +1964,40 @@ def _validation_failure(
     }
 
 
+def _visibility_validation_failure(
+    detail: str,
+    *,
+    tool_name: str,
+    exc: ValidationError | None,
+    suggested_next_call: JSONObject | None = None,
+) -> JSONObject:
+    result = _validation_failure(
+        detail,
+        tool_name=tool_name,
+        exc=exc,
+        suggested_next_call=suggested_next_call,
+    )
+    lowered = detail.lower()
+    code_by_fragment = [
+        ("visibility and auth cannot be provided together", "VISIBILITY_CONFLICT"),
+        ("specific visibility requires selectors", "VISIBILITY_SELECTOR_REQUIRED"),
+        ("selectors are only allowed when mode=specific", "VISIBILITY_SELECTOR_UNEXPECTED"),
+        ("external_mode=specific requires external_selectors", "EXTERNAL_VISIBILITY_SELECTOR_REQUIRED"),
+        ("external_selectors are only allowed when external_mode=specific", "EXTERNAL_VISIBILITY_SELECTOR_UNEXPECTED"),
+        ("mode=everyone requires external_mode=workspace", "VISIBILITY_EXTERNAL_MODE_CONFLICT"),
+        ("external_selectors are not allowed when mode=everyone", "VISIBILITY_SELECTOR_UNEXPECTED"),
+    ]
+    for fragment, error_code in code_by_fragment:
+        if fragment in lowered:
+            result["error_code"] = error_code
+            result["message"] = fragment
+            details = result.get("details")
+            if isinstance(details, dict):
+                details["visibility_error"] = True
+            break
+    return result
+
+
 def _config_failure(*, tool_name: str, message: str, fix_hint: str) -> JSONObject:
     contract = _BUILDER_TOOL_CONTRACTS.get(tool_name or "")
     return {
@@ -1978,6 +2114,52 @@ def _public_error_message(error_code: str, error: QingflowApiError) -> str:
     return mapping.get(error_code, "requested builder resource is unavailable in the current route")
 
 
+_VISIBILITY_ALLOWED_VALUES: JSONObject = {
+    "visibility.mode": ["workspace", "everyone", "specific"],
+    "visibility.external_mode": ["not", "workspace", "specific"],
+    "visibility.selectors": [
+        "member_uids",
+        "member_emails",
+        "member_names",
+        "dept_ids",
+        "dept_names",
+        "role_ids",
+        "role_names",
+        "include_sub_departs",
+    ],
+    "visibility.external_selectors": ["member_ids", "member_emails", "dept_ids"],
+}
+
+
+_VISIBILITY_EXECUTION_NOTES = [
+    "visibility is the canonical public auth shape for packages, apps, views, charts, and portals",
+    "mode=workspace means internal workspace members; mode=everyone means all users; mode=specific requires selectors",
+    "external_mode defaults to not and controls external-user visibility independently unless mode=everyone",
+    "name selectors must resolve to exactly one member, department, or role; ambiguous names fail instead of guessing",
+    "when updating an existing resource, omit visibility to preserve the current backend auth",
+]
+
+
+_VISIBILITY_WORKSPACE_EXAMPLE: JSONObject = {
+    "mode": "workspace",
+    "selectors": {},
+    "external_mode": "not",
+    "external_selectors": {},
+}
+
+
+_VISIBILITY_SPECIFIC_EXAMPLE: JSONObject = {
+    "mode": "specific",
+    "selectors": {
+        "member_emails": ["owner@example.com"],
+        "role_names": ["项目经理"],
+        "include_sub_departs": False,
+    },
+    "external_mode": "not",
+    "external_selectors": {},
+}
+
+
 _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"],
@@ -2042,18 +2224,68 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "package_create": {
-        "allowed_keys": ["package_name", "icon", "color"],
+        "allowed_keys": ["package_name", "icon", "color", "visibility"],
         "aliases": {
             "packageName": "package_name",
             "iconName": "icon",
             "iconColor": "color",
         },
-        "allowed_values": {},
+        "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_values": {},
+        "execution_notes": [
+            "returns package base info plus normalized visibility",
+            "visibility is normalized from backend MemberAuthInfoVO auth",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "tag_id": 1001,
+        },
+    },
+    "package_update": {
+        "allowed_keys": ["tag_id", "package_name", "icon", "color", "visibility"],
+        "aliases": {
+            "tagId": "tag_id",
+            "packageName": "package_name",
+            "iconName": "icon",
+            "iconColor": "color",
+        },
+        "allowed_values": deepcopy(_VISIBILITY_ALLOWED_VALUES),
+        "execution_notes": [
+            "update package name, icon, color, and/or visibility",
+            *_VISIBILITY_EXECUTION_NOTES,
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "tag_id": 1001,
+            "package_name": "项目管理",
+            "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
+        },
+        "specific_visibility_example": {
+            "profile": "default",
+            "tag_id": 1001,
+            "visibility": deepcopy(_VISIBILITY_SPECIFIC_EXAMPLE),
         },
     },
     "solution_install": {
@@ -2273,7 +2505,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_schema_plan": {
-        "allowed_keys": ["app_key", "package_tag_id", "app_name", "icon", "color", "create_if_missing", "add_fields", "update_fields", "remove_fields"],
+        "allowed_keys": ["app_key", "package_tag_id", "app_name", "icon", "color", "visibility", "create_if_missing", "add_fields", "update_fields", "remove_fields"],
         "aliases": {
             "app_title": "app_name",
             "title": "app_name",
@@ -2301,13 +2533,19 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "field.type": [member.value for member in PublicFieldType],
             "field.relation_mode": [member.value for member in PublicRelationMode],
             "field_type_ids": sorted(FIELD_TYPE_ID_ALIASES.keys()),
+            **deepcopy(_VISIBILITY_ALLOWED_VALUES),
         },
+        "execution_notes": [
+            "create mode may set visibility for the new app; edit mode may update visibility on an existing app",
+            *_VISIBILITY_EXECUTION_NOTES,
+        ],
         "minimal_example": {
             "profile": "default",
             "app_name": "研发项目管理",
             "package_tag_id": 1001,
             "icon": "template",
             "color": "emerald",
+            "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
             "create_if_missing": True,
             "add_fields": [{"name": "项目名称", "type": "text"}],
             "update_fields": [],
@@ -2331,7 +2569,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_schema_apply": {
-        "allowed_keys": ["app_key", "package_tag_id", "app_name", "icon", "color", "create_if_missing", "publish", "add_fields", "update_fields", "remove_fields"],
+        "allowed_keys": ["app_key", "package_tag_id", "app_name", "icon", "color", "visibility", "create_if_missing", "publish", "add_fields", "update_fields", "remove_fields"],
         "aliases": {
             "app_title": "app_name",
             "title": "app_name",
@@ -2362,11 +2600,14 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "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()),
+            **deepcopy(_VISIBILITY_ALLOWED_VALUES),
         },
         "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 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",
             "backend 49614 is normalized to MULTIPLE_RELATION_FIELDS_UNSUPPORTED with a workaround message",
             "relation_mode=multiple maps to referenceConfig.optionalDataNum=0",
@@ -2386,6 +2627,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "package_tag_id": 1001,
             "icon": "template",
             "color": "emerald",
+            "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
             "create_if_missing": True,
             "publish": True,
             "add_fields": [{"name": "项目名称", "type": "text"}],
@@ -2637,7 +2879,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_views_plan": {
-        "allowed_keys": ["app_key", "upsert_views", "remove_views", "preset", "upsert_views[].view_key", "upsert_views[].buttons"],
+        "allowed_keys": ["app_key", "upsert_views", "remove_views", "preset", "upsert_views[].view_key", "upsert_views[].buttons", "upsert_views[].visibility"],
         "aliases": {
             "fields": "columns",
             "column_names": "columns",
@@ -2666,14 +2908,17 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "view.filter.operator": [member.value for member in ViewFilterOperator],
             "view.buttons.button_type": ["SYSTEM", "CUSTOM"],
             "view.buttons.config_type": ["TOP", "DETAIL"],
+            **deepcopy(_VISIBILITY_ALLOWED_VALUES),
         },
         "execution_notes": [
+            "upsert_views[].visibility may set per-view visibility; omit it to preserve an existing view's auth or default a new view to workspace/not",
             "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",
+            *_VISIBILITY_EXECUTION_NOTES,
         ],
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
-            "upsert_views": [{"name": "全部数据", "type": "table", "columns": ["项目名称"]}],
+            "upsert_views": [{"name": "全部数据", "type": "table", "columns": ["项目名称"], "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE)}],
             "remove_views": [],
         },
         "gantt_example": {
@@ -2694,7 +2939,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_views_apply": {
-        "allowed_keys": ["app_key", "publish", "upsert_views", "remove_views", "upsert_views[].view_key", "upsert_views[].buttons"],
+        "allowed_keys": ["app_key", "publish", "upsert_views", "remove_views", "upsert_views[].view_key", "upsert_views[].buttons", "upsert_views[].visibility"],
         "aliases": {
             "fields": "columns",
             "column_names": "columns",
@@ -2722,6 +2967,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "view.filter.operator": [member.value for member in ViewFilterOperator],
             "view.buttons.button_type": ["SYSTEM", "CUSTOM"],
             "view.buttons.config_type": ["TOP", "DETAIL"],
+            **deepcopy(_VISIBILITY_ALLOWED_VALUES),
         },
         "execution_notes": [
             "apply may return partial_success when some views land and others fail",
@@ -2729,13 +2975,15 @@ _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",
+            "upsert_views[].visibility may set per-view visibility; omit it to preserve an existing view's auth or default a new view to workspace/not",
             "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",
+            *_VISIBILITY_EXECUTION_NOTES,
         ],
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
             "publish": True,
-            "upsert_views": [{"name": "全部数据", "type": "table", "columns": ["项目名称"]}],
+            "upsert_views": [{"name": "全部数据", "type": "table", "columns": ["项目名称"], "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE)}],
             "remove_views": [],
         },
         "gantt_example": {
@@ -2764,6 +3012,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "returns builder-side app configuration summary and editability",
             "use this as the default builder discovery read before fields/layout/views/flow/charts detail reads",
             "editability reflects builder permissions, not end-user data visibility",
+            "returns normalized app visibility when backend auth is readable",
         ],
         "minimal_example": {
             "profile": "default",
@@ -2803,6 +3052,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "execution_notes": [
             "returns compact current view inventory for one app",
             "use this before app_views_apply when you need exact current view keys",
+            "view items include visibility_summary when backend view auth is readable",
         ],
         "minimal_example": {
             "profile": "default",
@@ -2830,6 +3080,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "returns a compact current chart inventory for one app",
             "use this before app_charts_apply when you need exact current chart_id values",
             "chart summaries do not include full qingbi config payloads",
+            "chart items include visibility_summary when QingBI base info is readable",
         ],
         "minimal_example": {
             "profile": "default",
@@ -2857,6 +3108,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "returns builder-side portal configuration detail plus a normalized component inventory",
             "chart and view components are returned as refs only; use builder chart_get or builder view_get for configuration detail",
             "being_draft=true reads the current draft view; being_draft=false reads live",
+            "returns normalized portal visibility when backend auth is readable",
         ],
         "minimal_example": {
             "profile": "default",
@@ -2865,7 +3117,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_charts_apply": {
-        "allowed_keys": ["app_key", "upsert_charts", "remove_chart_ids", "reorder_chart_ids"],
+        "allowed_keys": ["app_key", "upsert_charts", "remove_chart_ids", "reorder_chart_ids", "upsert_charts[].visibility"],
         "aliases": {
             "chart.id": "chart.chart_id",
             "chart.type": "chart.chart_type",
@@ -2877,17 +3129,20 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "allowed_values": {
             "chart.chart_type": [member.value for member in PublicChartType],
             "chart.filter.operator": [member.value for member in ViewFilterOperator],
+            **deepcopy(_VISIBILITY_ALLOWED_VALUES),
         },
         "execution_notes": [
             "app_charts_apply is immediate-live and does not publish",
             "chart matching precedence is chart_id first, then exact unique chart name",
             "when chart names are not unique, supply chart_id instead of guessing by name",
             "successful create results must return a real backend chart_id",
+            "upsert_charts[].visibility compiles to QingBI visibleAuth; omit it on updates to preserve the existing visibleAuth",
+            *_VISIBILITY_EXECUTION_NOTES,
         ],
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
-            "upsert_charts": [{"name": "数据总量", "chart_type": "target", "indicator_field_ids": []}],
+            "upsert_charts": [{"name": "数据总量", "chart_type": "target", "indicator_field_ids": [], "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE)}],
             "remove_chart_ids": [],
             "reorder_chart_ids": [],
         },
@@ -2900,6 +3155,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "returns one builder-side view definition detail",
             "does not return record data; use user-side view_get or record_list for runtime rows",
             "use this after builder portal_get when a component references a view_ref.view_key",
+            "returns normalized view visibility when backend auth is readable",
         ],
         "minimal_example": {
             "profile": "default",
@@ -2914,6 +3170,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "returns builder-side chart base info and chart config only",
             "chart_id is required; chart names are not accepted here",
             "does not return chart data; use user-side chart_get for runtime data access",
+            "returns normalized chart visibility from QingBI visibleAuth when readable",
         ],
         "minimal_example": {
             "profile": "default",
@@ -2921,7 +3178,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "portal_apply": {
-        "allowed_keys": ["dash_key", "dash_name", "package_tag_id", "publish", "sections", "auth", "icon", "color", "hide_copyright", "dash_global_config", "config"],
+        "allowed_keys": ["dash_key", "dash_name", "package_tag_id", "publish", "sections", "visibility", "auth", "icon", "color", "hide_copyright", "dash_global_config", "config"],
         "aliases": {
             "sourceType": "source_type",
             "chartRef": "chart_ref",
@@ -2935,7 +3192,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "viewRef": "view_ref",
             "dashStyleConfigBO": "dash_style_config",
         },
-        "allowed_values": {"section.source_type": ["chart", "view", "grid", "filter", "text", "link"]},
+        "allowed_values": {"section.source_type": ["chart", "view", "grid", "filter", "text", "link"], **deepcopy(_VISIBILITY_ALLOWED_VALUES)},
         "execution_notes": [
             "use exactly one resource mode",
             "update mode: dash_key",
@@ -2947,12 +3204,16 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "chart_ref resolves by chart_id first, then exact unique chart_name",
             "view_ref resolves by view_key first, then exact unique view_name",
             "position.pc/mobile is the canonical portal layout shape",
+            "visibility is the canonical public auth shape; auth is kept only as a deprecated compatibility alias",
+            "passing visibility and auth together is rejected as VISIBILITY_CONFLICT",
+            *_VISIBILITY_EXECUTION_NOTES,
         ],
         "minimal_example": {
             "profile": "default",
             "dash_name": "经营门户",
             "package_tag_id": 1001,
             "publish": True,
+            "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
             "sections": [
                 {
                     "title": "经营概览",