@qingflow-tech/qingflow-cli 1.1.61-beta.4 → 1.1.61-beta.5

package/src/qingflow_mcp/cli/commands/builder.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import argparse
+import sys
 from copy import deepcopy
 from pathlib import Path
 
@@ -18,6 +19,7 @@ from ...app_form_validator import (
     validate_declaration,
     validate_formula_expression,
 )
+from ...builder_facade.portals_schema import PORTALS_SUPPORTED_SCHEMA_KINDS
 from ...builder_facade.views_schema import VIEWS_SUPPORTED_SCHEMA_KINDS
 from ..context import CliContext
 from ..json_io import load_json_value
@@ -260,17 +262,39 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     portal_list = portal_subparsers.add_parser("list", help="列出可配置门户")
     portal_list.set_defaults(handler=_handle_portal_list, format_hint="builder_summary")
 
-    portal_get = portal_subparsers.add_parser("get", help="读取门户详情")
+    portal_schema = portal_subparsers.add_parser("schema", help="读取门户声明 Schema")
+    portal_schema.add_argument("--schema-version")
+    portal_schema.add_argument(
+        "--schema-kind",
+        choices=PORTALS_SUPPORTED_SCHEMA_KINDS,
+    )
+    portal_schema.set_defaults(handler=_handle_portal_schema, format_hint="builder_summary", force_json_output=True)
+
+    portal_get = portal_subparsers.add_parser("get", help="读取门户声明或详情")
     portal_get.add_argument("--dash-key", required=True)
     portal_get.add_argument("--being-draft", action=argparse.BooleanOptionalAction, default=True)
+    portal_get.add_argument(
+        "--schema-kind",
+        choices=("summary", "complete", "raw"),
+        default="summary",
+        help="summary/complete＝canonical 声明投影(重放提取锦点);raw＝原始归一响应",
+    )
+    portal_get.add_argument("--schema-version")
     portal_get.set_defaults(handler=_handle_portal_get, format_hint="builder_summary")
 
+    portal_validate = portal_subparsers.add_parser("validate", help="只校验门户声明，不访问后端")
+    portal_validate.add_argument("--file", required=True, help="门户声明 JSON 文件，- 表示 stdin")
+    portal_validate.add_argument("--schema-version", help="固定使用的门户 Schema 版本；缺省读文件内 schema_version，再缺省 latest")
+    portal_validate.set_defaults(handler=_handle_portal_validate, format_hint="builder_summary", force_json_output=True)
+
     portal_apply = portal_subparsers.add_parser("apply", help="更新门户")
+    portal_apply.add_argument("--file", help="声明文件主形态(完整 portal 声明 JSON，支持 - stdin)；与 patch 参数互斥")
+    portal_apply.add_argument("--schema-version", help="声明使用的 Schema 版本；缺省读文件内 schema_version，再缺省 latest")
     portal_apply.add_argument("--dash-key", default="")
     portal_apply.add_argument("--dash-name", default="")
     portal_apply.add_argument("--package-id", type=int)
-    portal_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=True)
-    portal_apply.add_argument("--payload-file")
+    portal_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=None, help="发布开关；--file 声明模式下缺省尊重声明内 publish 字段（再缺省 true），显式传参时覆盖声明值")
+    portal_apply.add_argument("--payload-file", help="兼容：完整门户 payload JSON(裸 DTO 透传)；新代码改用 --file")
     portal_apply.add_argument("--sections-file")
     portal_apply.add_argument("--layout-preset", default="")
     portal_apply.add_argument("--visibility-file")
@@ -981,8 +1005,36 @@ def _handle_portal_list(args: argparse.Namespace, context: CliContext) -> dict:
     return context.builder.portal_list(profile=args.profile)
 
 
+def _handle_portal_schema(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.portal_schema(
+        schema_version=getattr(args, "schema_version", None),
+        schema_kind=getattr(args, "schema_kind", None),
+    )
+
+
+def _handle_portal_validate(args: argparse.Namespace, context: CliContext) -> dict:
+    payload = load_json_value(
+        args.file,
+        option_name="--file",
+        max_bytes=2 * 1024 * 1024,
+        max_depth=64,
+    )
+    if not isinstance(payload, dict):
+        raise_config_error("builder portal validate --file must contain a JSON object")
+    return context.builder.portal_validate(
+        declaration=payload,
+        schema_version=getattr(args, "schema_version", None),
+    )
+
+
 def _handle_portal_get(args: argparse.Namespace, context: CliContext) -> dict:
-    return context.builder.portal_get(profile=args.profile, dash_key=args.dash_key, being_draft=bool(args.being_draft))
+    return context.builder.portal_get(
+        profile=args.profile,
+        dash_key=args.dash_key,
+        being_draft=bool(args.being_draft),
+        schema_kind=getattr(args, "schema_kind", "summary") or "summary",
+        schema_version=getattr(args, "schema_version", None),
+    )
 
 
 def _handle_view_get(args: argparse.Namespace, context: CliContext) -> dict:
@@ -1385,6 +1437,62 @@ def _handle_charts_apply(args: argparse.Namespace, context: CliContext) -> dict:
 
 
 def _handle_portal_apply(args: argparse.Namespace, context: CliContext) -> dict:
+    file_declaration = (
+        load_json_value(args.file, option_name="--file", max_bytes=4 * 1024 * 1024, max_depth=64)
+        if getattr(args, "file", None)
+        else None
+    )
+    file_schema_version: str | None = None
+    legacy_args_used = False
+    if file_declaration is not None:
+        if not isinstance(file_declaration, dict):
+            raise_config_error("builder portal apply --file must contain a JSON object")
+        legacy_keys = (
+            getattr(args, "sections_file", None),
+            getattr(args, "patch_sections_file", None),
+            getattr(args, "visibility_file", None),
+            getattr(args, "auth_file", None),
+            getattr(args, "dash_global_config_file", None),
+            getattr(args, "config_file", None),
+            getattr(args, "payload_file", None),
+            getattr(args, "icon", None),
+            getattr(args, "color", None),
+            (getattr(args, "dash_name", "") or ""),
+            (getattr(args, "layout_preset", "") or ""),
+        )
+        if any(bool(item) for item in legacy_keys):
+            raise_config_error(
+                "builder portal apply --file cannot be combined with patch parameters.",
+                fix_hint="Put the full declaration in the --file JSON; keep only --schema-version/--publish/--dash-key flags.",
+                error_code="ARGUMENT_ERROR",
+            )
+        if getattr(args, "package_id", None) is not None:
+            file_declaration.setdefault("package_tag_id", args.package_id)
+        if getattr(args, "dash_key", ""):
+            file_declaration["dash_key"] = args.dash_key
+        # publish 三态对齐 MCP（声明值优先、显式 flag 最高）：声明内 publish 弹出后由 flag 解析——
+        # flag 未传时尊重声明值（含幂等重放的 publish:false），声明也未写时才缺省 true。
+        flag_publish = getattr(args, "publish", None)
+        declaration_publish = file_declaration.pop("publish", None)
+        effective_publish = (
+            bool(flag_publish)
+            if flag_publish is not None
+            else (bool(declaration_publish) if declaration_publish is not None else True)
+        )
+        file_schema_version = str(file_declaration.pop("schema_version", None) or file_declaration.pop("schemaVersion", None) or "").strip() or None
+        effective_schema_version = getattr(args, "schema_version", None) or file_schema_version
+        return context.builder.portal_apply(
+            profile=args.profile,
+            payload=file_declaration,
+            schema_version=effective_schema_version,
+            publish=effective_publish,
+        )
+    legacy_args_used = True
+    if legacy_args_used:
+        print(
+            "[deprecation] builder portal apply patch parameters are in a compatibility window; prefer `--file <declaration.json>`",
+            file=sys.stderr,
+        )
     payload = load_object_arg(args.payload_file, option_name="--payload-file") if getattr(args, "payload_file", None) else None
     payload_obj = payload if isinstance(payload, dict) else {}
     effective_dash_name = (args.dash_name or str(payload_obj.get("dash_name") or payload_obj.get("dashName") or payload_obj.get("name") or "")).strip()
@@ -1413,7 +1521,7 @@ def _handle_portal_apply(args: argparse.Namespace, context: CliContext) -> dict:
         dash_key=args.dash_key,
         dash_name=args.dash_name,
         package_id=args.package_id,
-        publish=bool(args.publish),
+        publish=bool(args.publish if args.publish is not None else True),
         sections=sections,
         layout_preset=args.layout_preset,
         visibility=load_object_arg(args.visibility_file, option_name="--visibility-file"),
@@ -1424,6 +1532,7 @@ def _handle_portal_apply(args: argparse.Namespace, context: CliContext) -> dict:
         dash_global_config=load_object_arg(args.dash_global_config_file, option_name="--dash-global-config-file"),
         config=load_object_arg(args.config_file, option_name="--config-file"),
         payload=payload,
+        schema_version=getattr(args, "schema_version", None),
         patch_sections=patch_sections,
     )
 

package/src/qingflow_mcp/public_surface.py

@@ -184,6 +184,8 @@ BUILDER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
     PublicToolSpec(BUILDER_DOMAIN, "app_views_get", ("app_views_get",), ("builder", "views", "get"), cli_show_effective_context=True),
     PublicToolSpec(BUILDER_DOMAIN, "app_views_validate", (), ("builder", "views", "validate"), mcp_public=True),
     PublicToolSpec(BUILDER_DOMAIN, "app_views_apply", ("app_views_apply",), ("builder", "views", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "portal_schema", (), ("builder", "portal", "schema"), mcp_public=True),
+    PublicToolSpec(BUILDER_DOMAIN, "portal_validate", (), ("builder", "portal", "validate"), mcp_public=True),
     PublicToolSpec(BUILDER_DOMAIN, "app_charts_apply", ("app_charts_apply",), ("builder", "charts", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
     PublicToolSpec(BUILDER_DOMAIN, "portal_apply", ("portal_apply",), ("builder", "portal", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
     PublicToolSpec(BUILDER_DOMAIN, "portal_delete", ("portal_delete",), ("builder", "portal", "delete"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),

package/src/qingflow_mcp/server_app_builder.py

@@ -482,13 +482,36 @@ def build_builder_server() -> PolicyAwareFastMCP:
     def portal_list(profile: str = DEFAULT_PROFILE) -> dict:
         return ai_builder.portal_list(profile=profile)
 
+    @server.tool()
+    def portal_schema(
+        schema_version: str | None = None,
+        schema_kind: str | None = None,
+    ) -> dict:
+        """Get a complete portals schema or a focused component schema such as chart, view, grid, or carousel."""
+        return ai_builder.portal_schema(schema_version=schema_version, schema_kind=schema_kind)
+
+    @server.tool()
+    def portal_validate(
+        declaration: dict | None = None,
+        schema_version: str | None = None,
+    ) -> dict:
+        return ai_builder.portal_validate(declaration=declaration or {}, schema_version=schema_version)
+
     @server.tool()
     def portal_get(
         profile: str = DEFAULT_PROFILE,
         dash_key: str = "",
         being_draft: bool = True,
+        schema_kind: str = "summary",
+        schema_version: str | None = None,
     ) -> dict:
-        return ai_builder.portal_get(profile=profile, dash_key=dash_key, being_draft=being_draft)
+        return ai_builder.portal_get(
+            profile=profile,
+            dash_key=dash_key,
+            being_draft=being_draft,
+            schema_kind=schema_kind,
+            schema_version=schema_version,
+        )
 
     @server.tool()
     def view_get(profile: str = DEFAULT_PROFILE, view_key: str = "") -> dict:
@@ -624,6 +647,10 @@ def build_builder_server() -> PolicyAwareFastMCP:
         color: str | None = None,
         hide_copyright: bool | None = None,
         dash_global_config: dict | None = None,
+        global_config: dict | None = None,
+        style_template_id: int | None = None,
+        overall_style: dict | None = None,
+        schema_version: str | None = None,
         config: dict | None = None,
         payload: dict | None = None,
         patch_sections: list[dict] | None = None,
@@ -660,6 +687,10 @@ def build_builder_server() -> PolicyAwareFastMCP:
             color=color,
             hide_copyright=hide_copyright,
             dash_global_config=dash_global_config,
+            global_config=global_config,
+            style_template_id=style_template_id,
+            overall_style=overall_style,
+            schema_version=schema_version,
             config=config or {},
             payload=payload,
             patch_sections=patch_sections,

package/src/qingflow_mcp/solution/compiler/icon_utils.py

@@ -312,6 +312,13 @@ def parse_workspace_icon(value: str | None) -> tuple[str | None, str | None, str
     stripped = str(value).strip()
     if not stripped:
         return None, None, None
+    if _looks_like_icon_url(stripped):
+        # URL 形态旧图标(如 https://…/dashboard_security.png)不是目录图标:目录名与
+        # 色均无法表达。返回 (None, None, None) 而不是按关键字把 URL 归一成假目录名
+        # ('dashboard' 命中 → 'view-grid')——后者经编译重编码会销毁存量 URL 图标,
+        # 并派生出不存在的默认色(r5 实测 50 门户 color diff 根因)。声明面按「未表达」
+        # 处理(读面 gap 记账);更新语义 apply 不触碰未指定图标,URL 原样存活。
+        return None, None, None
     if _looks_like_icon_json(stripped):
         try:
             payload = json.loads(stripped)
@@ -324,6 +331,11 @@ def parse_workspace_icon(value: str | None) -> tuple[str | None, str | None, str
     return normalize_workspace_icon_name(stripped), None, None
 
 
+def _looks_like_icon_url(value: str) -> bool:
+    lowered = value.strip().lower()
+    return lowered.startswith(("http://", "https://", "//"))
+
+
 def workspace_icon_config(value: str | None) -> dict[str, str | None]:
     icon_name, icon_color, icon_text = parse_workspace_icon(value)
     raw = str(value).strip() if value not in (None, "") else None
@@ -442,6 +454,67 @@ def encode_workspace_icon_with_defaults(
     )
 
 
+def update_workspace_icon_from_existing(
+    *,
+    icon: str | None,
+    color: str | None,
+    title: str,
+    existing_icon: str | None,
+    fallback_icon_name: str | None = None,
+) -> str:
+    """更新语义的 dashIcon 重编码(round-trip 保真)。
+
+    后端 updateDashBaseInfo 对 dashIcon 无校验直接透传落库;生产存量存在三类非目录形态:
+    文字图标(iconName 空 + iconText=名字首字)、旧版 URL 图标(icon 键携带 URL)、
+    空(iconName/iconText 均空)。encode_workspace_icon_with_defaults 的 fallback 语义
+    (为新建资源合成目录图标)会把「声明 icon 未指定」的存量形态重写为 fallback 图标。
+
+    更新语义规则:
+    - 声明 icon 显式指定且与存量 iconName 归一后一致 → JSON 级最小 patch:仅当声明
+      显式指定了不同 color 才改写 iconColor,否则存量 JSON 原串透传(byte 级保真);
+      iconText 等非目录形态键始终保留——生产存量存在 iconName+iconText 同设形态
+      (r7 全量实测 48 门),全量重编码会把 iconText 清成 null。
+    - 声明 icon 显式指定且为其他图标 → 走 encode(用户意图覆写);
+    - 声明 icon 未指定且无存量 → 走 encode_with_defaults(创建/首次合成);
+    - 声明 icon 未指定且有存量:
+      - color 也未指定 → 原样保留存量 JSON;
+      - color 指定 → JSON 级最小 patch(仅替换 iconColor,iconName/iconText/icon URL
+        等存量形态键原样保留)。
+    """
+    existing_payload = str(existing_icon or "").strip()
+    if existing_payload and _looks_like_icon_json(existing_payload):
+        try:
+            parsed = json.loads(existing_payload)
+        except ValueError:
+            parsed = None
+        if isinstance(parsed, dict):
+            existing_name, existing_color, _ = parse_workspace_icon(existing_payload)
+            if icon is None:
+                if color is None:
+                    return existing_payload
+                patched = dict(parsed)
+                patched["iconColor"] = color
+                return json.dumps(patched, ensure_ascii=False, separators=(",", ":"))
+            if (
+                existing_name is not None
+                and not _looks_like_icon_json(icon)
+                and not _looks_like_icon_url(icon)
+                and normalize_workspace_icon_name(icon) == existing_name
+            ):
+                if color is None or color == existing_color:
+                    return existing_payload
+                patched = dict(parsed)
+                patched["iconColor"] = color
+                return json.dumps(patched, ensure_ascii=False, separators=(",", ":"))
+    return encode_workspace_icon_with_defaults(
+        icon=icon,
+        color=color,
+        title=title,
+        fallback_icon_name=fallback_icon_name,
+        existing_icon=existing_icon,
+    )
+
+
 def normalize_workspace_icon_name(icon: str | None) -> str | None:
     if not icon:
         return None

package/src/qingflow_mcp/solution/executor.py

@@ -10,6 +10,7 @@ from ..tools.app_tools import AppTools
 from ..tools.navigation_tools import NavigationTools
 from ..tools.package_tools import PackageTools
 from ..tools.portal_tools import PortalTools
+from ..tools.portal_writer import PortalWriter
 from ..tools.qingbi_report_tools import QingbiReportTools
 from ..tools.record_tools import RecordTools
 from ..tools.role_tools import RoleTools
@@ -39,6 +40,7 @@ class SolutionExecutor:
         view_writer: "ViewWriter | None" = None,
         chart_tools: QingbiReportTools,
         portal_tools: PortalTools,
+        portal_writer: "PortalWriter | None" = None,
         navigation_tools: NavigationTools,
         workflow_tools: Any | None = None,
     ) -> None:
@@ -51,6 +53,7 @@ class SolutionExecutor:
         self.view_writer = view_writer
         self.chart_tools = chart_tools
         self.portal_tools = portal_tools
+        self.portal_writer = portal_writer or PortalWriter(portal_tools.sessions, portal_tools.backend)
         self.navigation_tools = navigation_tools
         self.workflow_tools = workflow_tools
 
@@ -624,7 +627,7 @@ class SolutionExecutor:
         result = portal_artifact
         if not dash_key:
             create_payload = self._resolve_portal_payload(compiled.portal_plan["create_payload"], store, base_payload=None)
-            result = self.portal_tools.portal_create(profile=profile, payload=create_payload)
+            result = self.portal_writer.create_portal(profile=profile, payload=create_payload)
             portal_result = result.get("result") or {}
             dash_key = portal_result.get("dashKey")
             store.set_artifact("portal", "result", result)
@@ -655,7 +658,7 @@ class SolutionExecutor:
                     ),
                 )
             update_payload = self._resolve_portal_payload(compiled.portal_plan["update_payload"], store, base_payload=base_payload)
-            self.portal_tools.portal_update(profile=profile, dash_key=dash_key, payload=update_payload)
+            self.portal_writer.update_portal(profile=profile, dash_key=dash_key, payload=update_payload)
             self._refresh_portal_artifact(profile=profile, store=store, being_draft=True, artifact_key="draft_result")
 
     def _build_navigation(self, profile: str, compiled: CompiledSolution, store: RunArtifactStore) -> None:

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -699,13 +699,36 @@ class AiBuilderTools(ToolBase):
         def portal_list(profile: str = DEFAULT_PROFILE) -> JSONObject:
             return self.portal_list(profile=profile)
 
+        @mcp.tool()
+        def portal_schema(
+            schema_version: str | None = None,
+            schema_kind: str | None = None,
+        ) -> JSONObject:
+            """Get a complete portals schema or a focused component schema such as chart, view, grid, or carousel."""
+            return self.portal_schema(schema_version=schema_version, schema_kind=schema_kind)
+
+        @mcp.tool()
+        def portal_validate(
+            declaration: JSONObject | None = None,
+            schema_version: str | None = None,
+        ) -> JSONObject:
+            return self.portal_validate(declaration=declaration or {}, schema_version=schema_version)
+
         @mcp.tool()
         def portal_get(
             profile: str = DEFAULT_PROFILE,
             dash_key: str = "",
             being_draft: bool = True,
+            schema_kind: str = "summary",
+            schema_version: str | None = None,
         ) -> JSONObject:
-            return self.portal_get(profile=profile, dash_key=dash_key, being_draft=being_draft)
+            return self.portal_get(
+                profile=profile,
+                dash_key=dash_key,
+                being_draft=being_draft,
+                schema_kind=schema_kind,
+                schema_version=schema_version,
+            )
 
         @mcp.tool()
         def view_get(profile: str = DEFAULT_PROFILE, view_key: str = "") -> JSONObject:
@@ -845,6 +868,10 @@ class AiBuilderTools(ToolBase):
             color: str | None = None,
             hide_copyright: bool | None = None,
             dash_global_config: JSONObject | None = None,
+            global_config: JSONObject | None = None,
+            style_template_id: int | None = None,
+            overall_style: JSONObject | None = None,
+            schema_version: str | None = None,
             config: JSONObject | None = None,
             payload: JSONObject | None = None,
             patch_sections: list[JSONObject] | None = None,
@@ -883,6 +910,10 @@ class AiBuilderTools(ToolBase):
                 color=color,
                 hide_copyright=hide_copyright,
                 dash_global_config=dash_global_config,
+                global_config=global_config,
+                style_template_id=style_template_id,
+                overall_style=overall_style,
+                schema_version=schema_version,
                 config=config or {},
                 payload=payload,
                 patch_sections=patch_sections,
@@ -2052,16 +2083,58 @@ class AiBuilderTools(ToolBase):
             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}
+    def portal_get(
+        self,
+        *,
+        profile: str,
+        dash_key: str,
+        being_draft: bool = True,
+        schema_kind: str = "summary",
+        schema_version: str | None = None,
+    ) -> JSONObject:
+        """读取门户详情;schema_kind=summary|complete 返回 canonical 声明,raw 为原始归一响应。"""
+        normalized_args = {"dash_key": dash_key, "being_draft": being_draft, "schema_kind": schema_kind, "schema_version": schema_version}
         return _publicize_package_fields(_safe_tool_call(
-            lambda: self._facade.portal_get(profile=profile, dash_key=dash_key, being_draft=being_draft),
+            lambda: self._facade.portal_get(
+                profile=profile,
+                dash_key=dash_key,
+                being_draft=being_draft,
+                schema_kind=schema_kind,
+                schema_version=schema_version,
+            ),
             error_code="PORTAL_GET_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "portal_get", "arguments": {"profile": profile, **normalized_args}},
         ))
 
+    def portal_schema(
+        self,
+        *,
+        schema_version: str | None = None,
+        schema_kind: str | None = None,
+    ) -> JSONObject:
+        """读取版本化门户声明 schema(纯离线)。"""
+        return _publicize_package_fields(_safe_tool_call(
+            lambda: self._facade.portal_schema(schema_version=schema_version, schema_kind=schema_kind),
+            error_code="PORTAL_SCHEMA_FAILED",
+            normalized_args={"schema_version": schema_version, "schema_kind": schema_kind},
+            suggested_next_call={"tool_name": "portal_schema", "arguments": {"schema_kind": "summary"}},
+        ))
+
+    def portal_validate(
+        self,
+        *,
+        declaration: JSONObject,
+        schema_version: str | None = None,
+    ) -> JSONObject:
+        """纯离线校验一条门户声明(不访问后端)。"""
+        return _publicize_package_fields(_safe_tool_call(
+            lambda: self._facade.portal_validate(declaration=declaration, schema_version=schema_version),
+            error_code="PORTAL_VALIDATE_FAILED",
+            normalized_args={"schema_version": schema_version},
+            suggested_next_call={"tool_name": "portal_schema", "arguments": {"schema_kind": "complete"}},
+        ))
+
     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}
@@ -4233,6 +4306,10 @@ class AiBuilderTools(ToolBase):
         color: str | None = None,
         hide_copyright: bool | None = None,
         dash_global_config: JSONObject | None = None,
+        global_config: JSONObject | None = None,
+        style_template_id: int | None = None,
+        overall_style: JSONObject | None = None,
+        schema_version: str | None = None,
         config: JSONObject | None = None,
         payload: JSONObject | None = None,
         patch_sections: list[JSONObject] | None = None,
@@ -4284,6 +4361,14 @@ class AiBuilderTools(ToolBase):
             request_payload["hide_copyright"] = hide_copyright
         if dash_global_config is not None:
             request_payload["dash_global_config"] = dash_global_config
+        if global_config is not None:
+            request_payload["global_config"] = global_config
+        if style_template_id is not None:
+            request_payload["style_template_id"] = style_template_id
+        if overall_style is not None:
+            request_payload["overall_style"] = overall_style
+        if schema_version is not None:
+            request_payload["schema_version"] = schema_version
         if config:
             merged_config = dict(request_payload.get("config") or {}) if isinstance(request_payload.get("config"), dict) else {}
             merged_config.update(config)
@@ -4315,16 +4400,24 @@ class AiBuilderTools(ToolBase):
             ))
         normalized_args = request.model_dump(mode="json")
         normalized_args["package_id"] = normalized_args.pop("package_tag_id", package_id)
-        icon_failure = _validate_workspace_icon_for_builder(
-            tool_name="portal_apply",
-            icon=str(request.icon or ""),
-            color=str(request.color or ""),
-            creating=not bool(str(request.dash_key or "").strip()),
-        )
+        portal_creating = not bool(str(request.dash_key or "").strip())
+        # icon/color 目录校验仅对创建语义生效(CLI 防呆,后端 createDash 亦无校验):
+        # 更新语义(dash_key 定位)后端 updateDashBaseInfo 对 dashIcon 无目录校验直接
+        # 透传落库,生产存量存在旧版 hex 色值(#13c2c2 等)——提取透传的重放声明会被
+        # 目录校验拒之门外(WORKSPACE_ICON_COLOR_NOT_FOUND),故更新语义不做目录校验。
+        if portal_creating:
+            icon_failure = _validate_workspace_icon_for_builder(
+                tool_name="portal_apply",
+                icon=str(request.icon or ""),
+                color=str(request.color or ""),
+                creating=True,
+            )
+        else:
+            icon_failure = None
         if icon_failure is not None:
             return self._attach_apply_envelope(profile, "portal_apply", icon_failure)
         result = _publicize_package_fields(_safe_tool_call(
-            lambda: self._facade.portal_apply(profile=profile, request=request),
+            lambda: self._facade.portal_apply(profile=profile, request=request, schema_version=schema_version),
             error_code="PORTAL_APPLY_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "portal_apply", "arguments": {"profile": profile, **normalized_args}},
@@ -5738,6 +5831,11 @@ def _publicize_package_fields(value):
     }
     public: JSONObject = {}
     for key, item in value.items():
+        if key == "declaration":
+            # canonical 声明保持 schema 契约命名(package_tag_id 等),不做公开名重命名,
+            # 否则 get 投影的 declaration 无法直接回喂 validate/apply(round-trip 破坏)。
+            public[key] = item
+            continue
         public_key = key_map.get(key, key)
         public[public_key] = _publicize_package_fields(item)
     return public

package/src/qingflow_mcp/tools/portal_tools.py

@@ -14,8 +14,10 @@ class PortalTools(ToolBase):
     类型：门户配置工具。
     主要职责：
     1. 查询门户列表与详情；
-    2. 维护门户基础信息与配置；
-    3. 执行门户发布与删除操作。
+    2. 执行门户发布与删除操作。
+
+    创建/更新写入已下沉 ``PortalWriter``（tools/portal_writer.py），
+    公开层唯一入口是 ``builder portal apply`` / ``portal_apply``。
     """
 
     def register(self, mcp: FastMCP) -> None:
@@ -32,18 +34,6 @@ class PortalTools(ToolBase):
         def portal_get_base_info(profile: str = DEFAULT_PROFILE, dash_key: str = "") -> JSONObject:
             return self.portal_get_base_info(profile=profile, dash_key=dash_key)
 
-        @mcp.tool()
-        def portal_create(profile: str = DEFAULT_PROFILE, payload: JSONObject | None = None) -> JSONObject:
-            return self.portal_create(profile=profile, payload=payload or {})
-
-        @mcp.tool(description=self._high_risk_tool_description(operation="update", target="portal base settings"))
-        def portal_update_base_info(profile: str = DEFAULT_PROFILE, dash_key: str = "", payload: JSONObject | None = None) -> JSONObject:
-            return self.portal_update_base_info(profile=profile, dash_key=dash_key, payload=payload or {})
-
-        @mcp.tool(description=self._high_risk_tool_description(operation="update", target="portal configuration"))
-        def portal_update(profile: str = DEFAULT_PROFILE, dash_key: str = "", payload: JSONObject | None = None) -> JSONObject:
-            return self.portal_update(profile=profile, dash_key=dash_key, payload=payload or {})
-
         @mcp.tool(description=self._high_risk_tool_description(operation="delete", target="portal configuration"))
         def portal_delete(profile: str = DEFAULT_PROFILE, dash_key: str = "") -> JSONObject:
             return self.portal_delete(profile=profile, dash_key=dash_key)
@@ -70,16 +60,6 @@ class PortalTools(ToolBase):
 
         return self._run(profile, runner, tool_name='门户详情')
 
-    def portal_create(self, *, profile: str, payload: JSONObject) -> JSONObject:
-        """执行门户相关逻辑。"""
-        body = self._require_dict(payload)
-
-        def runner(session_profile, context):
-            result = self.backend.request("POST", context, "/dash", json_body=body)
-            return {"profile": profile, "ws_id": session_profile.selected_ws_id, "result": result}
-
-        return self._run(profile, runner, tool_name='创建门户')
-
     def portal_get_base_info(self, *, profile: str, dash_key: str) -> JSONObject:
         """执行门户相关逻辑。"""
         self._require_dash_key(dash_key)
@@ -119,36 +99,6 @@ class PortalTools(ToolBase):
 
         return self._run(profile, runner, tool_name='门户基础信息')
 
-    def portal_update_base_info(self, *, profile: str, dash_key: str, payload: JSONObject) -> JSONObject:
-        """执行门户相关逻辑。"""
-        self._require_dash_key(dash_key)
-        body = self._require_dict(payload)
-
-        def runner(session_profile, context):
-            result = self.backend.request("POST", context, f"/dash/{dash_key}/baseInfo", json_body=body)
-            return self._attach_human_review_notice(
-                {"profile": profile, "ws_id": session_profile.selected_ws_id, "dash_key": dash_key, "result": result},
-                operation="update",
-                target="portal base settings",
-            )
-
-        return self._run(profile, runner, tool_name='更新门户基础信息')
-
-    def portal_update(self, *, profile: str, dash_key: str, payload: JSONObject) -> JSONObject:
-        """执行门户相关逻辑。"""
-        self._require_dash_key(dash_key)
-        body = self._require_dict(payload)
-
-        def runner(session_profile, context):
-            result = self.backend.request("POST", context, f"/dash/{dash_key}", json_body=body)
-            return self._attach_human_review_notice(
-                {"profile": profile, "ws_id": session_profile.selected_ws_id, "dash_key": dash_key, "result": result},
-                operation="update",
-                target="portal configuration",
-            )
-
-        return self._run(profile, runner, tool_name='更新门户配置')
-
     def portal_delete(self, *, profile: str, dash_key: str) -> JSONObject:
         """执行门户相关逻辑。"""
         self._require_dash_key(dash_key)