@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
@@ -699,13 +699,36 @@ class AiBuilderTools(ToolBase):
699
699
  def portal_list(profile: str = DEFAULT_PROFILE) -> JSONObject:
700
700
  return self.portal_list(profile=profile)
701
701
 
702
+ @mcp.tool()
703
+ def portal_schema(
704
+ schema_version: str | None = None,
705
+ schema_kind: str | None = None,
706
+ ) -> JSONObject:
707
+ """Get a complete portals schema or a focused component schema such as chart, view, grid, or carousel."""
708
+ return self.portal_schema(schema_version=schema_version, schema_kind=schema_kind)
709
+
710
+ @mcp.tool()
711
+ def portal_validate(
712
+ declaration: JSONObject | None = None,
713
+ schema_version: str | None = None,
714
+ ) -> JSONObject:
715
+ return self.portal_validate(declaration=declaration or {}, schema_version=schema_version)
716
+
702
717
  @mcp.tool()
703
718
  def portal_get(
704
719
  profile: str = DEFAULT_PROFILE,
705
720
  dash_key: str = "",
706
721
  being_draft: bool = True,
722
+ schema_kind: str = "summary",
723
+ schema_version: str | None = None,
707
724
  ) -> JSONObject:
708
- return self.portal_get(profile=profile, dash_key=dash_key, being_draft=being_draft)
725
+ return self.portal_get(
726
+ profile=profile,
727
+ dash_key=dash_key,
728
+ being_draft=being_draft,
729
+ schema_kind=schema_kind,
730
+ schema_version=schema_version,
731
+ )
709
732
 
710
733
  @mcp.tool()
711
734
  def view_get(profile: str = DEFAULT_PROFILE, view_key: str = "") -> JSONObject:
@@ -835,7 +858,6 @@ class AiBuilderTools(ToolBase):
835
858
  dash_name: str = "",
836
859
  name: str = "",
837
860
  package_id: int | None = None,
838
- publish: bool = True,
839
861
  sections: list[JSONObject] | None = None,
840
862
  pages: list[JSONObject] | None = None,
841
863
  layout_preset: str = "",
@@ -845,6 +867,10 @@ class AiBuilderTools(ToolBase):
845
867
  color: str | None = None,
846
868
  hide_copyright: bool | None = None,
847
869
  dash_global_config: JSONObject | None = None,
870
+ global_config: JSONObject | None = None,
871
+ style_template_id: int | None = None,
872
+ overall_style: JSONObject | None = None,
873
+ schema_version: str | None = None,
848
874
  config: JSONObject | None = None,
849
875
  payload: JSONObject | None = None,
850
876
  patch_sections: list[JSONObject] | None = None,
@@ -873,7 +899,6 @@ class AiBuilderTools(ToolBase):
873
899
  dash_name=dash_name,
874
900
  name=name,
875
901
  package_id=package_id,
876
- publish=publish,
877
902
  sections=sections or [],
878
903
  pages=pages or [],
879
904
  layout_preset=layout_preset,
@@ -883,6 +908,10 @@ class AiBuilderTools(ToolBase):
883
908
  color=color,
884
909
  hide_copyright=hide_copyright,
885
910
  dash_global_config=dash_global_config,
911
+ global_config=global_config,
912
+ style_template_id=style_template_id,
913
+ overall_style=overall_style,
914
+ schema_version=schema_version,
886
915
  config=config or {},
887
916
  payload=payload,
888
917
  patch_sections=patch_sections,
@@ -2052,16 +2081,58 @@ class AiBuilderTools(ToolBase):
2052
2081
  suggested_next_call={"tool_name": "portal_list", "arguments": {"profile": profile}},
2053
2082
  ))
2054
2083
 
2055
- def portal_get(self, *, profile: str, dash_key: str, being_draft: bool = True) -> JSONObject:
2056
- """执行门户相关逻辑。"""
2057
- normalized_args = {"dash_key": dash_key, "being_draft": being_draft}
2084
+ def portal_get(
2085
+ self,
2086
+ *,
2087
+ profile: str,
2088
+ dash_key: str,
2089
+ being_draft: bool = True,
2090
+ schema_kind: str = "summary",
2091
+ schema_version: str | None = None,
2092
+ ) -> JSONObject:
2093
+ """读取门户详情;schema_kind=summary|complete 返回 canonical 声明,raw 为原始归一响应。"""
2094
+ normalized_args = {"dash_key": dash_key, "being_draft": being_draft, "schema_kind": schema_kind, "schema_version": schema_version}
2058
2095
  return _publicize_package_fields(_safe_tool_call(
2059
- lambda: self._facade.portal_get(profile=profile, dash_key=dash_key, being_draft=being_draft),
2096
+ lambda: self._facade.portal_get(
2097
+ profile=profile,
2098
+ dash_key=dash_key,
2099
+ being_draft=being_draft,
2100
+ schema_kind=schema_kind,
2101
+ schema_version=schema_version,
2102
+ ),
2060
2103
  error_code="PORTAL_GET_FAILED",
2061
2104
  normalized_args=normalized_args,
2062
2105
  suggested_next_call={"tool_name": "portal_get", "arguments": {"profile": profile, **normalized_args}},
2063
2106
  ))
2064
2107
 
2108
+ def portal_schema(
2109
+ self,
2110
+ *,
2111
+ schema_version: str | None = None,
2112
+ schema_kind: str | None = None,
2113
+ ) -> JSONObject:
2114
+ """读取版本化门户声明 schema(纯离线)。"""
2115
+ return _publicize_package_fields(_safe_tool_call(
2116
+ lambda: self._facade.portal_schema(schema_version=schema_version, schema_kind=schema_kind),
2117
+ error_code="PORTAL_SCHEMA_FAILED",
2118
+ normalized_args={"schema_version": schema_version, "schema_kind": schema_kind},
2119
+ suggested_next_call={"tool_name": "portal_schema", "arguments": {"schema_kind": "summary"}},
2120
+ ))
2121
+
2122
+ def portal_validate(
2123
+ self,
2124
+ *,
2125
+ declaration: JSONObject,
2126
+ schema_version: str | None = None,
2127
+ ) -> JSONObject:
2128
+ """纯离线校验一条门户声明(不访问后端)。"""
2129
+ return _publicize_package_fields(_safe_tool_call(
2130
+ lambda: self._facade.portal_validate(declaration=declaration, schema_version=schema_version),
2131
+ error_code="PORTAL_VALIDATE_FAILED",
2132
+ normalized_args={"schema_version": schema_version},
2133
+ suggested_next_call={"tool_name": "portal_schema", "arguments": {"schema_kind": "complete"}},
2134
+ ))
2135
+
2065
2136
  def portal_read_summary(self, *, profile: str, dash_key: str, being_draft: bool = True) -> JSONObject:
2066
2137
  """执行门户相关逻辑。"""
2067
2138
  normalized_args = {"dash_key": dash_key, "being_draft": being_draft}
@@ -4223,7 +4294,6 @@ class AiBuilderTools(ToolBase):
4223
4294
  dash_name: str = "",
4224
4295
  name: str = "",
4225
4296
  package_id: int | None = None,
4226
- publish: bool = True,
4227
4297
  sections: list[JSONObject] | None = None,
4228
4298
  pages: list[JSONObject] | None = None,
4229
4299
  layout_preset: str = "",
@@ -4233,6 +4303,10 @@ class AiBuilderTools(ToolBase):
4233
4303
  color: str | None = None,
4234
4304
  hide_copyright: bool | None = None,
4235
4305
  dash_global_config: JSONObject | None = None,
4306
+ global_config: JSONObject | None = None,
4307
+ style_template_id: int | None = None,
4308
+ overall_style: JSONObject | None = None,
4309
+ schema_version: str | None = None,
4236
4310
  config: JSONObject | None = None,
4237
4311
  payload: JSONObject | None = None,
4238
4312
  patch_sections: list[JSONObject] | None = None,
@@ -4241,7 +4315,6 @@ class AiBuilderTools(ToolBase):
4241
4315
  if patch_sections is not None:
4242
4316
  normalized_args = {
4243
4317
  "dash_key": dash_key,
4244
- "publish": publish,
4245
4318
  "patch_sections": patch_sections,
4246
4319
  }
4247
4320
  return self._attach_apply_envelope(profile, "portal_apply", _publicize_package_fields(_safe_tool_call(
@@ -4249,7 +4322,6 @@ class AiBuilderTools(ToolBase):
4249
4322
  profile=profile,
4250
4323
  dash_key=dash_key,
4251
4324
  patch_sections=patch_sections,
4252
- publish=publish,
4253
4325
  ),
4254
4326
  error_code="PORTAL_PATCH_FAILED",
4255
4327
  normalized_args=normalized_args,
@@ -4264,8 +4336,6 @@ class AiBuilderTools(ToolBase):
4264
4336
  request_payload["name"] = name
4265
4337
  if package_id is not None:
4266
4338
  request_payload["package_id"] = package_id
4267
- if "publish" not in request_payload or publish is False:
4268
- request_payload["publish"] = publish
4269
4339
  if sections:
4270
4340
  request_payload["sections"] = sections
4271
4341
  if pages:
@@ -4284,6 +4354,14 @@ class AiBuilderTools(ToolBase):
4284
4354
  request_payload["hide_copyright"] = hide_copyright
4285
4355
  if dash_global_config is not None:
4286
4356
  request_payload["dash_global_config"] = dash_global_config
4357
+ if global_config is not None:
4358
+ request_payload["global_config"] = global_config
4359
+ if style_template_id is not None:
4360
+ request_payload["style_template_id"] = style_template_id
4361
+ if overall_style is not None:
4362
+ request_payload["overall_style"] = overall_style
4363
+ if schema_version is not None:
4364
+ request_payload["schema_version"] = schema_version
4287
4365
  if config:
4288
4366
  merged_config = dict(request_payload.get("config") or {}) if isinstance(request_payload.get("config"), dict) else {}
4289
4367
  merged_config.update(config)
@@ -4301,7 +4379,6 @@ class AiBuilderTools(ToolBase):
4301
4379
  "profile": profile,
4302
4380
  "dash_name": dash_name or "业务门户",
4303
4381
  "package_id": package_id or 1001,
4304
- "publish": True,
4305
4382
  "layout_preset": "dashboard_2col",
4306
4383
  "sections": [
4307
4384
  {
@@ -4315,20 +4392,34 @@ class AiBuilderTools(ToolBase):
4315
4392
  ))
4316
4393
  normalized_args = request.model_dump(mode="json")
4317
4394
  normalized_args["package_id"] = normalized_args.pop("package_tag_id", package_id)
4318
- icon_failure = _validate_workspace_icon_for_builder(
4319
- tool_name="portal_apply",
4320
- icon=str(request.icon or ""),
4321
- color=str(request.color or ""),
4322
- creating=not bool(str(request.dash_key or "").strip()),
4323
- )
4395
+ portal_creating = not bool(str(request.dash_key or "").strip())
4396
+ # icon/color 目录校验仅对创建语义生效(CLI 防呆,后端 createDash 亦无校验):
4397
+ # 更新语义(dash_key 定位)后端 updateDashBaseInfo 对 dashIcon 无目录校验直接
4398
+ # 透传落库,生产存量存在旧版 hex 色值(#13c2c2 等)——提取透传的重放声明会被
4399
+ # 目录校验拒之门外(WORKSPACE_ICON_COLOR_NOT_FOUND),故更新语义不做目录校验。
4400
+ if portal_creating:
4401
+ icon_failure = _validate_workspace_icon_for_builder(
4402
+ tool_name="portal_apply",
4403
+ icon=str(request.icon or ""),
4404
+ color=str(request.color or ""),
4405
+ creating=True,
4406
+ )
4407
+ else:
4408
+ icon_failure = None
4324
4409
  if icon_failure is not None:
4325
4410
  return self._attach_apply_envelope(profile, "portal_apply", icon_failure)
4326
4411
  result = _publicize_package_fields(_safe_tool_call(
4327
- lambda: self._facade.portal_apply(profile=profile, request=request),
4412
+ lambda: self._facade.portal_apply(profile=profile, request=request, schema_version=schema_version),
4328
4413
  error_code="PORTAL_APPLY_FAILED",
4329
4414
  normalized_args=normalized_args,
4330
4415
  suggested_next_call={"tool_name": "portal_apply", "arguments": {"profile": profile, **normalized_args}},
4331
4416
  ))
4417
+ # 更新语义(dash_key 定位)写成功后挂人工复核 notice:被收敛删除的
4418
+ # portal_update/portal_update_base_info 原带该防护(master 同款),
4419
+ # portal_apply 成为唯一写入口后在此恢复;创建语义不挂(新建资源
4420
+ # 是 agent 主路径,逐次人工复核不可行)。
4421
+ if not portal_creating and result.get("write_executed") and result.get("status") in {"success", "partial_success"}:
4422
+ result = self._attach_human_review_notice(result, operation="update", target="portal configuration")
4332
4423
  return self._attach_apply_envelope(profile, "portal_apply", result)
4333
4424
 
4334
4425
  def portal_delete(self, *, profile: str, dash_key: str) -> JSONObject:
@@ -4340,6 +4431,8 @@ class AiBuilderTools(ToolBase):
4340
4431
  normalized_args=normalized_args,
4341
4432
  suggested_next_call={"tool_name": "portal_delete", "arguments": {"profile": profile, **normalized_args}},
4342
4433
  ))
4434
+ if result.get("write_executed") and result.get("status") in {"success", "partial_success"}:
4435
+ result = self._attach_human_review_notice(result, operation="delete", target="portal configuration")
4343
4436
  return self._attach_apply_envelope(profile, "portal_delete", result)
4344
4437
 
4345
4438
  def app_publish_verify(
@@ -5738,6 +5831,11 @@ def _publicize_package_fields(value):
5738
5831
  }
5739
5832
  public: JSONObject = {}
5740
5833
  for key, item in value.items():
5834
+ if key == "declaration":
5835
+ # canonical 声明保持 schema 契约命名(package_tag_id 等),不做公开名重命名,
5836
+ # 否则 get 投影的 declaration 无法直接回喂 validate/apply(round-trip 破坏)。
5837
+ public[key] = item
5838
+ continue
5741
5839
  public_key = key_map.get(key, key)
5742
5840
  public[public_key] = _publicize_package_fields(item)
5743
5841
  return public
@@ -14,8 +14,10 @@ class PortalTools(ToolBase):
14
14
  类型:门户配置工具。
15
15
  主要职责:
16
16
  1. 查询门户列表与详情;
17
- 2. 维护门户基础信息与配置;
18
- 3. 执行门户发布与删除操作。
17
+ 2. 执行门户发布与删除操作。
18
+
19
+ 创建/更新写入已下沉 ``PortalWriter``(tools/portal_writer.py),
20
+ 公开层唯一入口是 ``builder portal apply`` / ``portal_apply``。
19
21
  """
20
22
 
21
23
  def register(self, mcp: FastMCP) -> None:
@@ -32,18 +34,6 @@ class PortalTools(ToolBase):
32
34
  def portal_get_base_info(profile: str = DEFAULT_PROFILE, dash_key: str = "") -> JSONObject:
33
35
  return self.portal_get_base_info(profile=profile, dash_key=dash_key)
34
36
 
35
- @mcp.tool()
36
- def portal_create(profile: str = DEFAULT_PROFILE, payload: JSONObject | None = None) -> JSONObject:
37
- return self.portal_create(profile=profile, payload=payload or {})
38
-
39
- @mcp.tool(description=self._high_risk_tool_description(operation="update", target="portal base settings"))
40
- def portal_update_base_info(profile: str = DEFAULT_PROFILE, dash_key: str = "", payload: JSONObject | None = None) -> JSONObject:
41
- return self.portal_update_base_info(profile=profile, dash_key=dash_key, payload=payload or {})
42
-
43
- @mcp.tool(description=self._high_risk_tool_description(operation="update", target="portal configuration"))
44
- def portal_update(profile: str = DEFAULT_PROFILE, dash_key: str = "", payload: JSONObject | None = None) -> JSONObject:
45
- return self.portal_update(profile=profile, dash_key=dash_key, payload=payload or {})
46
-
47
37
  @mcp.tool(description=self._high_risk_tool_description(operation="delete", target="portal configuration"))
48
38
  def portal_delete(profile: str = DEFAULT_PROFILE, dash_key: str = "") -> JSONObject:
49
39
  return self.portal_delete(profile=profile, dash_key=dash_key)
@@ -70,16 +60,6 @@ class PortalTools(ToolBase):
70
60
 
71
61
  return self._run(profile, runner, tool_name='门户详情')
72
62
 
73
- def portal_create(self, *, profile: str, payload: JSONObject) -> JSONObject:
74
- """执行门户相关逻辑。"""
75
- body = self._require_dict(payload)
76
-
77
- def runner(session_profile, context):
78
- result = self.backend.request("POST", context, "/dash", json_body=body)
79
- return {"profile": profile, "ws_id": session_profile.selected_ws_id, "result": result}
80
-
81
- return self._run(profile, runner, tool_name='创建门户')
82
-
83
63
  def portal_get_base_info(self, *, profile: str, dash_key: str) -> JSONObject:
84
64
  """执行门户相关逻辑。"""
85
65
  self._require_dash_key(dash_key)
@@ -119,36 +99,6 @@ class PortalTools(ToolBase):
119
99
 
120
100
  return self._run(profile, runner, tool_name='门户基础信息')
121
101
 
122
- def portal_update_base_info(self, *, profile: str, dash_key: str, payload: JSONObject) -> JSONObject:
123
- """执行门户相关逻辑。"""
124
- self._require_dash_key(dash_key)
125
- body = self._require_dict(payload)
126
-
127
- def runner(session_profile, context):
128
- result = self.backend.request("POST", context, f"/dash/{dash_key}/baseInfo", json_body=body)
129
- return self._attach_human_review_notice(
130
- {"profile": profile, "ws_id": session_profile.selected_ws_id, "dash_key": dash_key, "result": result},
131
- operation="update",
132
- target="portal base settings",
133
- )
134
-
135
- return self._run(profile, runner, tool_name='更新门户基础信息')
136
-
137
- def portal_update(self, *, profile: str, dash_key: str, payload: JSONObject) -> JSONObject:
138
- """执行门户相关逻辑。"""
139
- self._require_dash_key(dash_key)
140
- body = self._require_dict(payload)
141
-
142
- def runner(session_profile, context):
143
- result = self.backend.request("POST", context, f"/dash/{dash_key}", json_body=body)
144
- return self._attach_human_review_notice(
145
- {"profile": profile, "ws_id": session_profile.selected_ws_id, "dash_key": dash_key, "result": result},
146
- operation="update",
147
- target="portal configuration",
148
- )
149
-
150
- return self._run(profile, runner, tool_name='更新门户配置')
151
-
152
102
  def portal_delete(self, *, profile: str, dash_key: str) -> JSONObject:
153
103
  """执行门户相关逻辑。"""
154
104
  self._require_dash_key(dash_key)
@@ -0,0 +1,59 @@
1
+ from __future__ import annotations
2
+
3
+ from typing import Any
4
+
5
+ from ..errors import QingflowApiError, raise_tool_error
6
+ from ..json_types import JSONObject, JSONValue
7
+ from .base import ToolBase
8
+
9
+
10
+ class PortalWriter(ToolBase):
11
+ """门户写手——POST /dash、POST /dash/{dashKey}、POST /dash/{dashKey}/baseInfo 的唯一落点。
12
+
13
+ 仅限 builder facade 与 solution executor 内部使用;
14
+ 不注册 MCP 工具、不进 public_surface、不暴露 CLI。
15
+ 公开层的门户创建/更新唯一入口是 ``builder portal apply`` / ``portal_apply``。
16
+ """
17
+
18
+ def create_portal(self, *, profile: str, payload: JSONObject) -> JSONObject:
19
+ """创建门户(内部 writer;公开入口请走 builder portal apply)。"""
20
+ body = self._require_dict(payload)
21
+ return self._request(profile, "POST", "/dash", tool_name="创建门户", json_body=body)
22
+
23
+ def update_portal(self, *, profile: str, dash_key: str, payload: JSONObject) -> JSONObject:
24
+ """更新门户配置(内部 writer;公开入口请走 builder portal apply)。"""
25
+ self._require_dash_key(dash_key)
26
+ body = self._require_dict(payload)
27
+ return self._request(profile, "POST", f"/dash/{dash_key}", tool_name="更新门户配置", json_body=body)
28
+
29
+ def update_portal_base_info(self, *, profile: str, dash_key: str, payload: JSONObject) -> JSONObject:
30
+ """更新门户基础信息(内部 writer;公开入口请走 builder portal apply)。"""
31
+ self._require_dash_key(dash_key)
32
+ body = self._require_dict(payload)
33
+ return self._request(profile, "POST", f"/dash/{dash_key}/baseInfo", tool_name="更新门户基础信息", json_body=body)
34
+
35
+ def _require_dash_key(self, dash_key: str) -> None:
36
+ if not dash_key:
37
+ raise_tool_error(QingflowApiError.config_error("dash_key is required"))
38
+
39
+ def _request(
40
+ self,
41
+ profile: str,
42
+ method: str,
43
+ path: str,
44
+ *,
45
+ json_body: JSONValue = None,
46
+ params: JSONObject | None = None,
47
+ tool_name: str,
48
+ **extra: Any,
49
+ ) -> JSONObject:
50
+ def runner(session_profile, context):
51
+ result = self.backend.request(method, context, path, json_body=json_body, params=params)
52
+ response: JSONObject = {"profile": profile, "ws_id": session_profile.selected_ws_id, "result": result}
53
+ response.update(extra)
54
+ return response
55
+
56
+ return self._run(profile, runner, tool_name=tool_name)
57
+
58
+
59
+ __all__ = ["PortalWriter", "QingflowApiError", "raise_tool_error"]
@@ -39,6 +39,7 @@ from .record_tools import RecordTools
39
39
  from .role_tools import RoleTools
40
40
  from .view_tools import ViewTools
41
41
  from .view_writer import ViewWriter
42
+ from .portal_writer import PortalWriter
42
43
  from .workspace_tools import WorkspaceTools
43
44
 
44
45
  STAGED_BUILD_MODES = {"preflight", "plan", "apply", "repair"}
@@ -1431,6 +1432,7 @@ class SolutionTools(ToolBase):
1431
1432
  view_writer=ViewWriter(self.sessions, self.backend),
1432
1433
  chart_tools=QingbiReportTools(self.sessions, self.backend),
1433
1434
  portal_tools=PortalTools(self.sessions, self.backend),
1435
+ portal_writer=PortalWriter(self.sessions, self.backend),
1434
1436
  navigation_tools=NavigationTools(self.sessions, self.backend),
1435
1437
  )
1436
1438