@qingflow-tech/qingflow-cli 1.1.61 → 1.1.62

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. package/README.md +3 -3
  2. package/package.json +1 -1
  3. package/pyproject.toml +3 -1
  4. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md +1 -1
  5. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md +6 -258
  6. package/skills/qingflow-cli/reference/builder/20-build-complete-system.md +2 -2
  7. package/skills/qingflow-cli/reference/builder/30-schema-fields.md +22 -5
  8. package/skills/qingflow-cli/reference/builder/70-portal.md +71 -36
  9. package/skills/qingflow-cli/reference/builder/reference/app-delivery-sop.md +3 -3
  10. package/skills/qingflow-cli/reference/examples/portal/portal_apply_v1alpha1.example.json +100 -0
  11. package/skills/qingflow-cli/reference/examples/portal/portal_sections_all_types.example.json +6 -7
  12. package/src/qingflow_mcp/app_form_compat.py +3 -0
  13. package/src/qingflow_mcp/app_form_validator.py +89 -20
  14. package/src/qingflow_mcp/builder_facade/app_form.py +629 -112
  15. package/src/qingflow_mcp/builder_facade/models.py +197 -15
  16. package/src/qingflow_mcp/builder_facade/portals_schema.py +397 -0
  17. package/src/qingflow_mcp/builder_facade/schemas/app_form/manifest.json +15 -1
  18. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/complete.json +112 -38
  19. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/address.json +31 -8
  20. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_content_classification.json +146 -0
  21. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_content_extraction.json +146 -0
  22. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_content_generation.json +146 -0
  23. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_document_parsing.json +146 -0
  24. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_image_generation.json +146 -0
  25. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_image_recognition.json +146 -0
  26. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_machine_translation.json +146 -0
  27. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_text_summary.json +146 -0
  28. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/amount.json +6 -10
  29. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/attachment.json +33 -10
  30. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/code_block.json +6 -10
  31. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/data_relation.json +11 -18
  32. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/date.json +4 -8
  33. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/date_duration.json +146 -0
  34. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/datetime.json +4 -8
  35. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/department.json +6 -10
  36. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/email.json +4 -8
  37. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/embed_field.json +146 -0
  38. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/image_select.json +146 -0
  39. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/link.json +4 -8
  40. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/location.json +146 -0
  41. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/long_text.json +4 -8
  42. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/member.json +6 -10
  43. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/multi_select.json +4 -8
  44. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/number.json +6 -10
  45. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ocr.json +146 -0
  46. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/phone.json +4 -8
  47. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/q_linker.json +8 -12
  48. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/relation.json +73 -15
  49. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/rich_text.json +146 -0
  50. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/single_choice.json +4 -8
  51. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/single_select.json +4 -8
  52. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/subtable.json +90 -29
  53. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/text.json +4 -8
  54. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/formula.json +43 -0
  55. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/summary.json +27 -19
  56. package/src/qingflow_mcp/builder_facade/schemas/portals/manifest.json +59 -0
  57. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/complete.json +1397 -0
  58. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/carousel.json +193 -0
  59. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/chart.json +643 -0
  60. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/favourite.json +203 -0
  61. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/filter.json +249 -0
  62. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/grid.json +265 -0
  63. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/link.json +131 -0
  64. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/task.json +199 -0
  65. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/text.json +123 -0
  66. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/view.json +196 -0
  67. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/summary.json +800 -0
  68. package/src/qingflow_mcp/builder_facade/schemas/views/v1alpha1/complete.json +1 -1
  69. package/src/qingflow_mcp/builder_facade/schemas/views/v1alpha1/details/display.json +1 -1
  70. package/src/qingflow_mcp/builder_facade/schemas/views/v1alpha1/summary.json +1 -1
  71. package/src/qingflow_mcp/builder_facade/service.py +1359 -92
  72. package/src/qingflow_mcp/cli/commands/builder.py +120 -5
  73. package/src/qingflow_mcp/public_surface.py +2 -0
  74. package/src/qingflow_mcp/server_app_builder.py +34 -5
  75. package/src/qingflow_mcp/session_store.py +14 -1
  76. package/src/qingflow_mcp/solution/compiler/icon_utils.py +73 -0
  77. package/src/qingflow_mcp/solution/executor.py +5 -2
  78. package/src/qingflow_mcp/tools/ai_builder_tools.py +118 -20
  79. package/src/qingflow_mcp/tools/portal_tools.py +4 -54
  80. package/src/qingflow_mcp/tools/portal_writer.py +59 -0
  81. package/src/qingflow_mcp/tools/solution_tools.py +2 -0
@@ -1,6 +1,7 @@
1
1
  from __future__ import annotations
2
2
 
3
3
  import argparse
4
+ import sys
4
5
  from copy import deepcopy
5
6
  from pathlib import Path
6
7
 
@@ -18,6 +19,7 @@ from ...app_form_validator import (
18
19
  validate_declaration,
19
20
  validate_formula_expression,
20
21
  )
22
+ from ...builder_facade.portals_schema import PORTALS_SUPPORTED_SCHEMA_KINDS
21
23
  from ...builder_facade.views_schema import VIEWS_SUPPORTED_SCHEMA_KINDS
22
24
  from ..context import CliContext
23
25
  from ..json_io import load_json_value
@@ -260,17 +262,38 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
260
262
  portal_list = portal_subparsers.add_parser("list", help="列出可配置门户")
261
263
  portal_list.set_defaults(handler=_handle_portal_list, format_hint="builder_summary")
262
264
 
263
- portal_get = portal_subparsers.add_parser("get", help="读取门户详情")
265
+ portal_schema = portal_subparsers.add_parser("schema", help="读取门户声明 Schema")
266
+ portal_schema.add_argument("--schema-version")
267
+ portal_schema.add_argument(
268
+ "--schema-kind",
269
+ choices=PORTALS_SUPPORTED_SCHEMA_KINDS,
270
+ )
271
+ portal_schema.set_defaults(handler=_handle_portal_schema, format_hint="builder_summary", force_json_output=True)
272
+
273
+ portal_get = portal_subparsers.add_parser("get", help="读取门户声明或详情")
264
274
  portal_get.add_argument("--dash-key", required=True)
265
275
  portal_get.add_argument("--being-draft", action=argparse.BooleanOptionalAction, default=True)
276
+ portal_get.add_argument(
277
+ "--schema-kind",
278
+ choices=("summary", "complete", "raw"),
279
+ default="summary",
280
+ help="summary/complete=canonical 声明投影(重放提取锦点);raw=原始归一响应",
281
+ )
282
+ portal_get.add_argument("--schema-version")
266
283
  portal_get.set_defaults(handler=_handle_portal_get, format_hint="builder_summary")
267
284
 
285
+ portal_validate = portal_subparsers.add_parser("validate", help="只校验门户声明,不访问后端")
286
+ portal_validate.add_argument("--file", required=True, help="门户声明 JSON 文件,- 表示 stdin")
287
+ portal_validate.add_argument("--schema-version", help="固定使用的门户 Schema 版本;缺省读文件内 schema_version,再缺省 latest")
288
+ portal_validate.set_defaults(handler=_handle_portal_validate, format_hint="builder_summary", force_json_output=True)
289
+
268
290
  portal_apply = portal_subparsers.add_parser("apply", help="更新门户")
291
+ portal_apply.add_argument("--file", help="声明文件主形态(完整 portal 声明 JSON,支持 - stdin);与 patch 参数互斥")
292
+ portal_apply.add_argument("--schema-version", help="声明使用的 Schema 版本;缺省读文件内 schema_version,再缺省 latest")
269
293
  portal_apply.add_argument("--dash-key", default="")
270
294
  portal_apply.add_argument("--dash-name", default="")
271
295
  portal_apply.add_argument("--package-id", type=int)
272
- portal_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=True)
273
- portal_apply.add_argument("--payload-file")
296
+ portal_apply.add_argument("--payload-file", help="兼容:完整门户 payload JSON(裸 DTO 透传);新代码改用 --file")
274
297
  portal_apply.add_argument("--sections-file")
275
298
  portal_apply.add_argument("--layout-preset", default="")
276
299
  portal_apply.add_argument("--visibility-file")
@@ -981,8 +1004,36 @@ def _handle_portal_list(args: argparse.Namespace, context: CliContext) -> dict:
981
1004
  return context.builder.portal_list(profile=args.profile)
982
1005
 
983
1006
 
1007
+ def _handle_portal_schema(args: argparse.Namespace, context: CliContext) -> dict:
1008
+ return context.builder.portal_schema(
1009
+ schema_version=getattr(args, "schema_version", None),
1010
+ schema_kind=getattr(args, "schema_kind", None),
1011
+ )
1012
+
1013
+
1014
+ def _handle_portal_validate(args: argparse.Namespace, context: CliContext) -> dict:
1015
+ payload = load_json_value(
1016
+ args.file,
1017
+ option_name="--file",
1018
+ max_bytes=2 * 1024 * 1024,
1019
+ max_depth=64,
1020
+ )
1021
+ if not isinstance(payload, dict):
1022
+ raise_config_error("builder portal validate --file must contain a JSON object")
1023
+ return context.builder.portal_validate(
1024
+ declaration=payload,
1025
+ schema_version=getattr(args, "schema_version", None),
1026
+ )
1027
+
1028
+
984
1029
  def _handle_portal_get(args: argparse.Namespace, context: CliContext) -> dict:
985
- return context.builder.portal_get(profile=args.profile, dash_key=args.dash_key, being_draft=bool(args.being_draft))
1030
+ return context.builder.portal_get(
1031
+ profile=args.profile,
1032
+ dash_key=args.dash_key,
1033
+ being_draft=bool(args.being_draft),
1034
+ schema_kind=getattr(args, "schema_kind", "summary") or "summary",
1035
+ schema_version=getattr(args, "schema_version", None),
1036
+ )
986
1037
 
987
1038
 
988
1039
  def _handle_view_get(args: argparse.Namespace, context: CliContext) -> dict:
@@ -1385,6 +1436,70 @@ def _handle_charts_apply(args: argparse.Namespace, context: CliContext) -> dict:
1385
1436
 
1386
1437
 
1387
1438
  def _handle_portal_apply(args: argparse.Namespace, context: CliContext) -> dict:
1439
+ file_declaration = (
1440
+ load_json_value(args.file, option_name="--file", max_bytes=4 * 1024 * 1024, max_depth=64)
1441
+ if getattr(args, "file", None)
1442
+ else None
1443
+ )
1444
+ file_schema_version: str | None = None
1445
+ legacy_args_used = False
1446
+ if file_declaration is not None:
1447
+ if not isinstance(file_declaration, dict):
1448
+ raise_config_error("builder portal apply --file must contain a JSON object")
1449
+ legacy_keys = (
1450
+ getattr(args, "sections_file", None),
1451
+ getattr(args, "patch_sections_file", None),
1452
+ getattr(args, "visibility_file", None),
1453
+ getattr(args, "auth_file", None),
1454
+ getattr(args, "dash_global_config_file", None),
1455
+ getattr(args, "config_file", None),
1456
+ getattr(args, "payload_file", None),
1457
+ getattr(args, "icon", None),
1458
+ getattr(args, "color", None),
1459
+ (getattr(args, "dash_name", "") or ""),
1460
+ (getattr(args, "layout_preset", "") or ""),
1461
+ )
1462
+ if any(bool(item) for item in legacy_keys):
1463
+ raise_config_error(
1464
+ "builder portal apply --file cannot be combined with patch parameters.",
1465
+ fix_hint="Put the full declaration in the --file JSON; keep only --schema-version/--publish/--dash-key flags.",
1466
+ error_code="ARGUMENT_ERROR",
1467
+ )
1468
+ if getattr(args, "package_id", None) is not None:
1469
+ file_declaration.setdefault("package_tag_id", args.package_id)
1470
+ if getattr(args, "dash_key", ""):
1471
+ file_declaration["dash_key"] = args.dash_key
1472
+ file_schema_version = str(file_declaration.pop("schema_version", None) or file_declaration.pop("schemaVersion", None) or "").strip() or None
1473
+ effective_schema_version = getattr(args, "schema_version", None) or file_schema_version
1474
+ return context.builder.portal_apply(
1475
+ profile=args.profile,
1476
+ payload=file_declaration,
1477
+ schema_version=effective_schema_version,
1478
+ )
1479
+ # deprecation 提示仅在实际使用 patch 参数时打印(review §5 噪声收敛):
1480
+ # 纯 flag 调用(--dash-key/--publish/--schema-version/--package-id 定位或发布
1481
+ # 开关)不是 patch 形态,不该被提示;判定集与 --file 互斥检查的 patch 参数集一致。
1482
+ patch_args_used = any(
1483
+ bool(item)
1484
+ for item in (
1485
+ getattr(args, "sections_file", None),
1486
+ getattr(args, "patch_sections_file", None),
1487
+ getattr(args, "visibility_file", None),
1488
+ getattr(args, "auth_file", None),
1489
+ getattr(args, "dash_global_config_file", None),
1490
+ getattr(args, "config_file", None),
1491
+ getattr(args, "payload_file", None),
1492
+ getattr(args, "icon", None),
1493
+ getattr(args, "color", None),
1494
+ (getattr(args, "dash_name", "") or ""),
1495
+ (getattr(args, "layout_preset", "") or ""),
1496
+ )
1497
+ )
1498
+ if patch_args_used:
1499
+ print(
1500
+ "[deprecation] builder portal apply patch parameters are in a compatibility window; prefer `--file <declaration.json>`",
1501
+ file=sys.stderr,
1502
+ )
1388
1503
  payload = load_object_arg(args.payload_file, option_name="--payload-file") if getattr(args, "payload_file", None) else None
1389
1504
  payload_obj = payload if isinstance(payload, dict) else {}
1390
1505
  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 +1528,6 @@ def _handle_portal_apply(args: argparse.Namespace, context: CliContext) -> dict:
1413
1528
  dash_key=args.dash_key,
1414
1529
  dash_name=args.dash_name,
1415
1530
  package_id=args.package_id,
1416
- publish=bool(args.publish),
1417
1531
  sections=sections,
1418
1532
  layout_preset=args.layout_preset,
1419
1533
  visibility=load_object_arg(args.visibility_file, option_name="--visibility-file"),
@@ -1424,6 +1538,7 @@ def _handle_portal_apply(args: argparse.Namespace, context: CliContext) -> dict:
1424
1538
  dash_global_config=load_object_arg(args.dash_global_config_file, option_name="--dash-global-config-file"),
1425
1539
  config=load_object_arg(args.config_file, option_name="--config-file"),
1426
1540
  payload=payload,
1541
+ schema_version=getattr(args, "schema_version", None),
1427
1542
  patch_sections=patch_sections,
1428
1543
  )
1429
1544
 
@@ -182,6 +182,8 @@ BUILDER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
182
182
  PublicToolSpec(BUILDER_DOMAIN, "app_views_get", ("app_views_get",), ("builder", "views", "get"), cli_show_effective_context=True),
183
183
  PublicToolSpec(BUILDER_DOMAIN, "app_views_validate", (), ("builder", "views", "validate"), mcp_public=True),
184
184
  PublicToolSpec(BUILDER_DOMAIN, "app_views_apply", ("app_views_apply",), ("builder", "views", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
185
+ PublicToolSpec(BUILDER_DOMAIN, "portal_schema", (), ("builder", "portal", "schema"), mcp_public=True),
186
+ PublicToolSpec(BUILDER_DOMAIN, "portal_validate", (), ("builder", "portal", "validate"), mcp_public=True),
185
187
  PublicToolSpec(BUILDER_DOMAIN, "app_charts_apply", ("app_charts_apply",), ("builder", "charts", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
186
188
  PublicToolSpec(BUILDER_DOMAIN, "portal_apply", ("portal_apply",), ("builder", "portal", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
187
189
  PublicToolSpec(BUILDER_DOMAIN, "portal_delete", ("portal_delete",), ("builder", "portal", "delete"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
@@ -482,13 +482,36 @@ def build_builder_server() -> FastMCP:
482
482
  def portal_list(profile: str = DEFAULT_PROFILE) -> dict:
483
483
  return ai_builder.portal_list(profile=profile)
484
484
 
485
+ @server.tool()
486
+ def portal_schema(
487
+ schema_version: str | None = None,
488
+ schema_kind: str | None = None,
489
+ ) -> dict:
490
+ """Get a complete portals schema or a focused component schema such as chart, view, grid, or carousel."""
491
+ return ai_builder.portal_schema(schema_version=schema_version, schema_kind=schema_kind)
492
+
493
+ @server.tool()
494
+ def portal_validate(
495
+ declaration: dict | None = None,
496
+ schema_version: str | None = None,
497
+ ) -> dict:
498
+ return ai_builder.portal_validate(declaration=declaration or {}, schema_version=schema_version)
499
+
485
500
  @server.tool()
486
501
  def portal_get(
487
502
  profile: str = DEFAULT_PROFILE,
488
503
  dash_key: str = "",
489
504
  being_draft: bool = True,
505
+ schema_kind: str = "summary",
506
+ schema_version: str | None = None,
490
507
  ) -> dict:
491
- return ai_builder.portal_get(profile=profile, dash_key=dash_key, being_draft=being_draft)
508
+ return ai_builder.portal_get(
509
+ profile=profile,
510
+ dash_key=dash_key,
511
+ being_draft=being_draft,
512
+ schema_kind=schema_kind,
513
+ schema_version=schema_version,
514
+ )
492
515
 
493
516
  @server.tool()
494
517
  def view_get(profile: str = DEFAULT_PROFILE, view_key: str = "") -> dict:
@@ -607,14 +630,13 @@ def build_builder_server() -> FastMCP:
607
630
  apps=apps,
608
631
  )
609
632
 
610
- @server.tool()
633
+ @server.tool(description=ai_builder._high_risk_tool_description(operation="update", target="portal configuration"))
611
634
  def portal_apply(
612
635
  profile: str = DEFAULT_PROFILE,
613
636
  dash_key: str = "",
614
637
  dash_name: str = "",
615
638
  name: str = "",
616
639
  package_id: int | None = None,
617
- publish: bool = True,
618
640
  sections: list[dict] | None = None,
619
641
  pages: list[dict] | None = None,
620
642
  layout_preset: str = "",
@@ -624,6 +646,10 @@ def build_builder_server() -> FastMCP:
624
646
  color: str | None = None,
625
647
  hide_copyright: bool | None = None,
626
648
  dash_global_config: dict | None = None,
649
+ global_config: dict | None = None,
650
+ style_template_id: int | None = None,
651
+ overall_style: dict | None = None,
652
+ schema_version: str | None = None,
627
653
  config: dict | None = None,
628
654
  payload: dict | None = None,
629
655
  patch_sections: list[dict] | None = None,
@@ -650,7 +676,6 @@ def build_builder_server() -> FastMCP:
650
676
  dash_name=dash_name,
651
677
  name=name,
652
678
  package_id=package_id,
653
- publish=publish,
654
679
  sections=sections or [],
655
680
  pages=pages or [],
656
681
  layout_preset=layout_preset,
@@ -660,12 +685,16 @@ def build_builder_server() -> FastMCP:
660
685
  color=color,
661
686
  hide_copyright=hide_copyright,
662
687
  dash_global_config=dash_global_config,
688
+ global_config=global_config,
689
+ style_template_id=style_template_id,
690
+ overall_style=overall_style,
691
+ schema_version=schema_version,
663
692
  config=config or {},
664
693
  payload=payload,
665
694
  patch_sections=patch_sections,
666
695
  )
667
696
 
668
- @server.tool()
697
+ @server.tool(description=ai_builder._high_risk_tool_description(operation="delete", target="portal configuration"))
669
698
  def portal_delete(
670
699
  profile: str = DEFAULT_PROFILE,
671
700
  dash_key: str = "",
@@ -2,6 +2,7 @@ from __future__ import annotations
2
2
 
3
3
  import json
4
4
  import os
5
+ import time
5
6
  from collections.abc import Callable
6
7
  from dataclasses import asdict, dataclass
7
8
  from datetime import datetime, timedelta, timezone
@@ -156,7 +157,19 @@ class SessionStore:
156
157
  raw_profile = payload.get("profiles", {}).get(profile)
157
158
  session_profile = SessionProfile.from_dict(raw_profile) if isinstance(raw_profile, dict) else None
158
159
  if profile in self._refreshing_profiles:
159
- return session_profile
160
+ if session_profile is not None:
161
+ return session_profile
162
+ # 并发刷新窗口内读到瞬时缺失:等待刷新完成后重读。不补这一步时,
163
+ # 工作线程(如门户内联图表创建的并发 chart_apply)会在另一线程
164
+ # 刷新 profile 期间拿到 None,调用方(select_workspace/update_route 等)
165
+ # 随即抛 KeyError(profile) 击穿整个 apply(实测「并发 chart 创建因
166
+ # 认证过期失败」的竞态入口)。
167
+ deadline = time.monotonic() + 2.0
168
+ while profile in self._refreshing_profiles and time.monotonic() < deadline:
169
+ time.sleep(0.05)
170
+ payload = self._load_profiles()
171
+ raw_profile = payload.get("profiles", {}).get(profile)
172
+ return SessionProfile.from_dict(raw_profile) if isinstance(raw_profile, dict) else None
160
173
  if self._should_refresh_profile(payload, session_profile) and self._refresh_profile(profile, session_profile):
161
174
  payload = self._load_profiles()
162
175
  raw_profile = payload.get("profiles", {}).get(profile)
@@ -312,6 +312,13 @@ def parse_workspace_icon(value: str | None) -> tuple[str | None, str | None, str
312
312
  stripped = str(value).strip()
313
313
  if not stripped:
314
314
  return None, None, None
315
+ if _looks_like_icon_url(stripped):
316
+ # URL 形态旧图标(如 https://…/dashboard_security.png)不是目录图标:目录名与
317
+ # 色均无法表达。返回 (None, None, None) 而不是按关键字把 URL 归一成假目录名
318
+ # ('dashboard' 命中 → 'view-grid')——后者经编译重编码会销毁存量 URL 图标,
319
+ # 并派生出不存在的默认色(r5 实测 50 门户 color diff 根因)。声明面按「未表达」
320
+ # 处理(读面 gap 记账);更新语义 apply 不触碰未指定图标,URL 原样存活。
321
+ return None, None, None
315
322
  if _looks_like_icon_json(stripped):
316
323
  try:
317
324
  payload = json.loads(stripped)
@@ -324,6 +331,11 @@ def parse_workspace_icon(value: str | None) -> tuple[str | None, str | None, str
324
331
  return normalize_workspace_icon_name(stripped), None, None
325
332
 
326
333
 
334
+ def _looks_like_icon_url(value: str) -> bool:
335
+ lowered = value.strip().lower()
336
+ return lowered.startswith(("http://", "https://", "//"))
337
+
338
+
327
339
  def workspace_icon_config(value: str | None) -> dict[str, str | None]:
328
340
  icon_name, icon_color, icon_text = parse_workspace_icon(value)
329
341
  raw = str(value).strip() if value not in (None, "") else None
@@ -442,6 +454,67 @@ def encode_workspace_icon_with_defaults(
442
454
  )
443
455
 
444
456
 
457
+ def update_workspace_icon_from_existing(
458
+ *,
459
+ icon: str | None,
460
+ color: str | None,
461
+ title: str,
462
+ existing_icon: str | None,
463
+ fallback_icon_name: str | None = None,
464
+ ) -> str:
465
+ """更新语义的 dashIcon 重编码(round-trip 保真)。
466
+
467
+ 后端 updateDashBaseInfo 对 dashIcon 无校验直接透传落库;生产存量存在三类非目录形态:
468
+ 文字图标(iconName 空 + iconText=名字首字)、旧版 URL 图标(icon 键携带 URL)、
469
+ 空(iconName/iconText 均空)。encode_workspace_icon_with_defaults 的 fallback 语义
470
+ (为新建资源合成目录图标)会把「声明 icon 未指定」的存量形态重写为 fallback 图标。
471
+
472
+ 更新语义规则:
473
+ - 声明 icon 显式指定且与存量 iconName 归一后一致 → JSON 级最小 patch:仅当声明
474
+ 显式指定了不同 color 才改写 iconColor,否则存量 JSON 原串透传(byte 级保真);
475
+ iconText 等非目录形态键始终保留——生产存量存在 iconName+iconText 同设形态
476
+ (r7 全量实测 48 门),全量重编码会把 iconText 清成 null。
477
+ - 声明 icon 显式指定且为其他图标 → 走 encode(用户意图覆写);
478
+ - 声明 icon 未指定且无存量 → 走 encode_with_defaults(创建/首次合成);
479
+ - 声明 icon 未指定且有存量:
480
+ - color 也未指定 → 原样保留存量 JSON;
481
+ - color 指定 → JSON 级最小 patch(仅替换 iconColor,iconName/iconText/icon URL
482
+ 等存量形态键原样保留)。
483
+ """
484
+ existing_payload = str(existing_icon or "").strip()
485
+ if existing_payload and _looks_like_icon_json(existing_payload):
486
+ try:
487
+ parsed = json.loads(existing_payload)
488
+ except ValueError:
489
+ parsed = None
490
+ if isinstance(parsed, dict):
491
+ existing_name, existing_color, _ = parse_workspace_icon(existing_payload)
492
+ if icon is None:
493
+ if color is None:
494
+ return existing_payload
495
+ patched = dict(parsed)
496
+ patched["iconColor"] = color
497
+ return json.dumps(patched, ensure_ascii=False, separators=(",", ":"))
498
+ if (
499
+ existing_name is not None
500
+ and not _looks_like_icon_json(icon)
501
+ and not _looks_like_icon_url(icon)
502
+ and normalize_workspace_icon_name(icon) == existing_name
503
+ ):
504
+ if color is None or color == existing_color:
505
+ return existing_payload
506
+ patched = dict(parsed)
507
+ patched["iconColor"] = color
508
+ return json.dumps(patched, ensure_ascii=False, separators=(",", ":"))
509
+ return encode_workspace_icon_with_defaults(
510
+ icon=icon,
511
+ color=color,
512
+ title=title,
513
+ fallback_icon_name=fallback_icon_name,
514
+ existing_icon=existing_icon,
515
+ )
516
+
517
+
445
518
  def normalize_workspace_icon_name(icon: str | None) -> str | None:
446
519
  if not icon:
447
520
  return None
@@ -10,6 +10,7 @@ from ..tools.app_tools import AppTools
10
10
  from ..tools.navigation_tools import NavigationTools
11
11
  from ..tools.package_tools import PackageTools
12
12
  from ..tools.portal_tools import PortalTools
13
+ from ..tools.portal_writer import PortalWriter
13
14
  from ..tools.qingbi_report_tools import QingbiReportTools
14
15
  from ..tools.record_tools import RecordTools
15
16
  from ..tools.role_tools import RoleTools
@@ -39,6 +40,7 @@ class SolutionExecutor:
39
40
  view_writer: "ViewWriter | None" = None,
40
41
  chart_tools: QingbiReportTools,
41
42
  portal_tools: PortalTools,
43
+ portal_writer: "PortalWriter | None" = None,
42
44
  navigation_tools: NavigationTools,
43
45
  workflow_tools: Any | None = None,
44
46
  ) -> None:
@@ -51,6 +53,7 @@ class SolutionExecutor:
51
53
  self.view_writer = view_writer
52
54
  self.chart_tools = chart_tools
53
55
  self.portal_tools = portal_tools
56
+ self.portal_writer = portal_writer or PortalWriter(portal_tools.sessions, portal_tools.backend)
54
57
  self.navigation_tools = navigation_tools
55
58
  self.workflow_tools = workflow_tools
56
59
 
@@ -624,7 +627,7 @@ class SolutionExecutor:
624
627
  result = portal_artifact
625
628
  if not dash_key:
626
629
  create_payload = self._resolve_portal_payload(compiled.portal_plan["create_payload"], store, base_payload=None)
627
- result = self.portal_tools.portal_create(profile=profile, payload=create_payload)
630
+ result = self.portal_writer.create_portal(profile=profile, payload=create_payload)
628
631
  portal_result = result.get("result") or {}
629
632
  dash_key = portal_result.get("dashKey")
630
633
  store.set_artifact("portal", "result", result)
@@ -655,7 +658,7 @@ class SolutionExecutor:
655
658
  ),
656
659
  )
657
660
  update_payload = self._resolve_portal_payload(compiled.portal_plan["update_payload"], store, base_payload=base_payload)
658
- self.portal_tools.portal_update(profile=profile, dash_key=dash_key, payload=update_payload)
661
+ self.portal_writer.update_portal(profile=profile, dash_key=dash_key, payload=update_payload)
659
662
  self._refresh_portal_artifact(profile=profile, store=store, being_draft=True, artifact_key="draft_result")
660
663
 
661
664
  def _build_navigation(self, profile: str, compiled: CompiledSolution, store: RunArtifactStore) -> None: