@qingflow-tech/qingflow-cli 1.1.61 → 1.1.62-beta.2

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 (97) hide show
  1. package/README.md +3 -3
  2. package/package.json +2 -1
  3. package/pyproject.toml +4 -1
  4. package/skills/qingflow-cli/SKILL.md +112 -3
  5. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md +1 -1
  6. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md +6 -258
  7. package/skills/qingflow-cli/reference/builder/20-build-complete-system.md +3 -3
  8. package/skills/qingflow-cli/reference/builder/30-schema-fields.md +22 -5
  9. package/skills/qingflow-cli/reference/builder/70-portal.md +111 -36
  10. package/skills/qingflow-cli/reference/builder/README.md +2 -2
  11. package/skills/qingflow-cli/reference/builder/reference/app-delivery-sop.md +3 -3
  12. package/skills/qingflow-cli/reference/examples/portal/portal_apply_v1alpha1.example.json +100 -0
  13. package/skills/qingflow-cli/reference/examples/portal/portal_sections_all_types.example.json +22 -6
  14. package/src/qingflow_mcp/app_form_compat.py +3 -0
  15. package/src/qingflow_mcp/app_form_validator.py +89 -20
  16. package/src/qingflow_mcp/builder_facade/app_form.py +629 -112
  17. package/src/qingflow_mcp/builder_facade/models.py +213 -15
  18. package/src/qingflow_mcp/builder_facade/portals_schema.py +397 -0
  19. package/src/qingflow_mcp/builder_facade/schemas/app_form/manifest.json +15 -1
  20. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/complete.json +112 -38
  21. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/address.json +31 -8
  22. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_content_classification.json +146 -0
  23. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_content_extraction.json +146 -0
  24. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_content_generation.json +146 -0
  25. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_document_parsing.json +146 -0
  26. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_image_generation.json +146 -0
  27. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_image_recognition.json +146 -0
  28. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_machine_translation.json +146 -0
  29. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_text_summary.json +146 -0
  30. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/amount.json +6 -10
  31. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/attachment.json +33 -10
  32. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/code_block.json +6 -10
  33. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/data_relation.json +11 -18
  34. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/date.json +4 -8
  35. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/date_duration.json +146 -0
  36. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/datetime.json +4 -8
  37. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/department.json +6 -10
  38. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/email.json +4 -8
  39. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/embed_field.json +146 -0
  40. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/image_select.json +146 -0
  41. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/link.json +4 -8
  42. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/location.json +146 -0
  43. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/long_text.json +4 -8
  44. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/member.json +6 -10
  45. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/multi_select.json +4 -8
  46. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/number.json +6 -10
  47. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ocr.json +146 -0
  48. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/phone.json +4 -8
  49. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/q_linker.json +8 -12
  50. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/relation.json +73 -15
  51. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/rich_text.json +146 -0
  52. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/single_choice.json +4 -8
  53. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/single_select.json +4 -8
  54. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/subtable.json +90 -29
  55. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/text.json +4 -8
  56. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/formula.json +43 -0
  57. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/summary.json +27 -19
  58. package/src/qingflow_mcp/builder_facade/schemas/portals/manifest.json +59 -0
  59. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/complete.json +1397 -0
  60. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/carousel.json +193 -0
  61. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/chart.json +643 -0
  62. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/favourite.json +203 -0
  63. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/filter.json +331 -0
  64. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/grid.json +265 -0
  65. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/link.json +131 -0
  66. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/task.json +199 -0
  67. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/text.json +123 -0
  68. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/view.json +196 -0
  69. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/summary.json +800 -0
  70. package/src/qingflow_mcp/builder_facade/schemas/views/v1alpha1/complete.json +1 -1
  71. package/src/qingflow_mcp/builder_facade/schemas/views/v1alpha1/details/display.json +1 -1
  72. package/src/qingflow_mcp/builder_facade/schemas/views/v1alpha1/summary.json +1 -1
  73. package/src/qingflow_mcp/builder_facade/service.py +1367 -92
  74. package/src/qingflow_mcp/cli/commands/builder.py +120 -5
  75. package/src/qingflow_mcp/cli/formatters.py +11 -0
  76. package/src/qingflow_mcp/cli/main.py +90 -2
  77. package/src/qingflow_mcp/cli/permission_gate.py +59 -0
  78. package/src/qingflow_mcp/cloud_context.py +16 -1
  79. package/src/qingflow_mcp/entity_permissions.py +10 -0
  80. package/src/qingflow_mcp/permission_catalog.json +1210 -0
  81. package/src/qingflow_mcp/public_surface.py +69 -8
  82. package/src/qingflow_mcp/response_trim.py +2 -1
  83. package/src/qingflow_mcp/server.py +12 -6
  84. package/src/qingflow_mcp/server_app_builder.py +43 -10
  85. package/src/qingflow_mcp/server_app_user.py +9 -5
  86. package/src/qingflow_mcp/server_cloud.py +43 -7
  87. package/src/qingflow_mcp/session_store.py +14 -1
  88. package/src/qingflow_mcp/solution/compiler/icon_utils.py +73 -0
  89. package/src/qingflow_mcp/solution/executor.py +5 -2
  90. package/src/qingflow_mcp/tool_catalog.py +388 -0
  91. package/src/qingflow_mcp/tool_catalog_i18n.py +184 -0
  92. package/src/qingflow_mcp/tool_policy.py +191 -0
  93. package/src/qingflow_mcp/tools/ai_builder_tools.py +118 -20
  94. package/src/qingflow_mcp/tools/base.py +1 -0
  95. package/src/qingflow_mcp/tools/portal_tools.py +4 -54
  96. package/src/qingflow_mcp/tools/portal_writer.py +59 -0
  97. package/src/qingflow_mcp/tools/solution_tools.py +2 -0
@@ -1,5 +1,6 @@
1
1
  from __future__ import annotations
2
2
 
3
+ import argparse
3
4
  from argparse import Namespace
4
5
  from dataclasses import dataclass
5
6
 
@@ -109,6 +110,7 @@ USER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
109
110
  PublicToolSpec(USER_DOMAIN, "record_export_direct", ("record_export_direct",), ("export", "direct"), cli_show_effective_context=True),
110
111
  PublicToolSpec(USER_DOMAIN, "record_code_block_run", ("record_code_block_run",), ("record", "code-block-run"), cli_show_effective_context=True, cli_context_write=True),
111
112
  PublicToolSpec(USER_DOMAIN, "task_list", ("task_list",), ("task", "list"), cli_show_effective_context=True),
113
+ PublicToolSpec(USER_DOMAIN, "task_workbench", cli_route=("task",), mcp_public=False),
112
114
  PublicToolSpec(USER_DOMAIN, "task_get", ("task_get",), ("task", "get"), cli_show_effective_context=True),
113
115
  PublicToolSpec(USER_DOMAIN, "task_action_execute", ("task_action_execute",), ("task", "action"), cli_show_effective_context=True, cli_context_write=True),
114
116
  PublicToolSpec(
@@ -130,12 +132,12 @@ USER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
130
132
 
131
133
 
132
134
  BUILDER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
133
- PublicToolSpec(BUILDER_DOMAIN, "auth_use_credential", ("auth_use_credential",), ("builder", "auth", "use-credential"), cli_public=False),
134
- PublicToolSpec(BUILDER_DOMAIN, "auth_whoami", ("auth_whoami",), ("builder", "auth", "whoami"), cli_public=False),
135
- PublicToolSpec(BUILDER_DOMAIN, "auth_logout", ("auth_logout",), ("builder", "auth", "logout"), cli_public=False),
135
+ PublicToolSpec(BUILDER_DOMAIN, "auth_use_credential", ("auth_use_credential",), cli_public=False),
136
+ PublicToolSpec(BUILDER_DOMAIN, "auth_whoami", ("auth_whoami",), cli_public=False),
137
+ PublicToolSpec(BUILDER_DOMAIN, "auth_logout", ("auth_logout",), cli_public=False),
136
138
  PublicToolSpec(BUILDER_DOMAIN, "get_login_link", ("get_login_link",), mcp_public=True, cli_public=False),
137
- PublicToolSpec(BUILDER_DOMAIN, "workspace_list", ("workspace_list",), ("builder", "workspace", "list"), cli_public=False),
138
- PublicToolSpec(BUILDER_DOMAIN, "workspace_get", ("workspace_get",), ("builder", "workspace", "get"), cli_public=False),
139
+ PublicToolSpec(BUILDER_DOMAIN, "workspace_list", ("workspace_list",), cli_public=False),
140
+ PublicToolSpec(BUILDER_DOMAIN, "workspace_get", ("workspace_get",), cli_public=False),
139
141
  PublicToolSpec(BUILDER_DOMAIN, "file_upload_local", ("file_upload_local",), ("builder", "file", "upload-local"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
140
142
  PublicToolSpec(BUILDER_DOMAIN, "feedback_submit", ("feedback_submit",), ("builder", "feedback", "submit"), has_contract=True),
141
143
  PublicToolSpec(BUILDER_DOMAIN, "builder_tool_contract", ("builder_tool_contract",), ("builder", "contract"), has_contract=False),
@@ -182,6 +184,8 @@ BUILDER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
182
184
  PublicToolSpec(BUILDER_DOMAIN, "app_views_get", ("app_views_get",), ("builder", "views", "get"), cli_show_effective_context=True),
183
185
  PublicToolSpec(BUILDER_DOMAIN, "app_views_validate", (), ("builder", "views", "validate"), mcp_public=True),
184
186
  PublicToolSpec(BUILDER_DOMAIN, "app_views_apply", ("app_views_apply",), ("builder", "views", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
187
+ PublicToolSpec(BUILDER_DOMAIN, "portal_schema", (), ("builder", "portal", "schema"), mcp_public=True),
188
+ PublicToolSpec(BUILDER_DOMAIN, "portal_validate", (), ("builder", "portal", "validate"), mcp_public=True),
185
189
  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
190
  PublicToolSpec(BUILDER_DOMAIN, "portal_apply", ("portal_apply",), ("builder", "portal", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
187
191
  PublicToolSpec(BUILDER_DOMAIN, "portal_delete", ("portal_delete",), ("builder", "portal", "delete"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
@@ -194,7 +198,8 @@ PUBLIC_TOOL_BY_KEY: dict[str, PublicToolSpec] = {spec.trim_key: spec for spec in
194
198
  PUBLIC_TOOL_BY_CLI_ROUTE: dict[tuple[str, ...], PublicToolSpec] = {
195
199
  spec.cli_route: spec
196
200
  for spec in ALL_PUBLIC_TOOL_SPECS
197
- if spec.cli_public and spec.cli_route is not None
201
+ # 隐藏命令仍有可达 handler,闸门绑定不能把“帮助不可见”误当成“不可执行”。
202
+ if spec.cli_route is not None
198
203
  }
199
204
  PUBLIC_TOOL_BY_CLI_ROUTE.update(
200
205
  {
@@ -205,6 +210,9 @@ PUBLIC_TOOL_BY_CLI_ROUTE.update(
205
210
  }
206
211
  )
207
212
 
213
+ # 这些 handler 只负责版本输出、参数迁移或本地授权自省,不会发起轻流业务请求。
214
+ NON_TOOL_CLI_HANDLER_ROUTES = frozenset({("version",), ("record", "schema"), ("tools", "permissions")})
215
+
208
216
 
209
217
  def public_tool_specs(domain: str | None = None) -> tuple[PublicToolSpec, ...]:
210
218
  if domain is None:
@@ -258,11 +266,13 @@ def cli_route_from_namespace(args: Namespace) -> tuple[str, ...] | None:
258
266
  record_command = getattr(args, "record_command", None)
259
267
  if record_command == "schema":
260
268
  schema_command = getattr(args, "record_schema_command", None)
261
- return (command, "schema", schema_command) if isinstance(schema_command, str) and schema_command else None
269
+ if isinstance(schema_command, str) and schema_command:
270
+ return (command, "schema", schema_command)
271
+ return (command, "schema")
262
272
  return (command, record_command) if isinstance(record_command, str) and record_command else None
263
273
  if command == "task":
264
274
  task_command = getattr(args, "task_command", None)
265
- return (command, task_command) if isinstance(task_command, str) and task_command else None
275
+ return (command, task_command) if isinstance(task_command, str) and task_command else (command,)
266
276
  if command != "builder":
267
277
  child_attr = f"{command}_command"
268
278
  child = getattr(args, child_attr, None)
@@ -283,3 +293,54 @@ def cli_route_from_namespace(args: Namespace) -> tuple[str, ...] | None:
283
293
  child_attr = f"builder_{builder_command.replace('-', '_')}_command"
284
294
  child = getattr(args, child_attr, None)
285
295
  return ("builder", builder_command, child) if isinstance(child, str) and child else None
296
+
297
+
298
+ def discover_cli_handler_routes(
299
+ parser: argparse.ArgumentParser,
300
+ ) -> dict[tuple[str, ...], tuple[str, ...]]:
301
+ """从 argparse 实际 handler 树枚举规范化路由及其实现,包含中间交互入口。"""
302
+ discovered: dict[tuple[str, ...], set[str]] = {}
303
+
304
+ def walk(current: argparse.ArgumentParser, path: tuple[str, ...], inherited: dict[str, object]) -> None:
305
+ attrs = dict(inherited)
306
+ for action in current._actions:
307
+ if isinstance(action, argparse._SubParsersAction):
308
+ continue
309
+ if action.dest != argparse.SUPPRESS and action.default != argparse.SUPPRESS:
310
+ attrs.setdefault(action.dest, action.default)
311
+ attrs.update(current._defaults)
312
+
313
+ handler = current._defaults.get("handler")
314
+ if callable(handler):
315
+ variants = [attrs]
316
+ for action in current._actions:
317
+ if isinstance(action, argparse._SubParsersAction) or action.choices is None:
318
+ continue
319
+ variants.extend({**attrs, action.dest: choice} for choice in action.choices)
320
+ for variant in variants:
321
+ route = cli_route_from_namespace(Namespace(**variant))
322
+ if route is None:
323
+ route = _normalize_cli_parser_path(path)
324
+ if route:
325
+ identity = f"{handler.__module__}:{handler.__qualname__}"
326
+ discovered.setdefault(route, set()).add(identity)
327
+
328
+ for action in current._actions:
329
+ if not isinstance(action, argparse._SubParsersAction):
330
+ continue
331
+ for name, child in action.choices.items():
332
+ next_attrs = dict(attrs)
333
+ next_attrs[action.dest] = name
334
+ walk(child, path + (name,), next_attrs)
335
+
336
+ walk(parser, (), {})
337
+ return {route: tuple(sorted(handlers)) for route, handlers in discovered.items()}
338
+
339
+
340
+ def _normalize_cli_parser_path(path: tuple[str, ...]) -> tuple[str, ...]:
341
+ normalized = list(path)
342
+ if normalized and normalized[0] == "build":
343
+ normalized[0] = "builder"
344
+ if len(normalized) > 1 and normalized[0] == "builder" and normalized[1] == "associated-resources":
345
+ normalized[1] = "associated-resource"
346
+ return tuple(normalized)
@@ -51,8 +51,9 @@ COMMON_ERROR_DROP_TOP = {
51
51
 
52
52
  SUCCESS_POLICY_BY_TOOL: dict[str, TransformFn] = {}
53
53
 
54
- #: 这两个校验命令的产出契约明确包含 ok 字段(供阶段 2 SKILL.md 引用),
54
+ #: 这些校验命令的产出契约明确包含 ok 字段(供阶段 2 SKILL.md 引用),
55
55
  #: 需在 success 裁剪时保留 ok(默认 COMMON_SUCCESS_DROP_TOP 会丢弃 ok)。
56
+ #: `builder:app_views_validate`(views 声明式校验)同属校验类工具,ok 同样进产出契约。
56
57
  _KEEP_OK_TOOLS = {
57
58
  "builder:app_form_validate_formula",
58
59
  "builder:app_form_validate_code_block",
@@ -2,8 +2,6 @@ from __future__ import annotations
2
2
 
3
3
  from datetime import date
4
4
 
5
- from mcp.server.fastmcp import FastMCP
6
-
7
5
  from .backend_client import BackendClient
8
6
  from .session_store import SessionStore
9
7
  from .tools.app_tools import AppTools
@@ -26,9 +24,11 @@ from .tools.task_context_tools import TaskContextTools
26
24
  from .tools.view_tools import ViewTools
27
25
  from .tools.workflow_tools import WorkflowTools
28
26
  from .tools.workspace_tools import WorkspaceTools
27
+ from .tool_catalog import stdio_server_bindings
28
+ from .tool_policy import PolicyAwareFastMCP, configure_tool_policy
29
29
 
30
30
 
31
- def _register_missing_builder_tools(server: FastMCP) -> None:
31
+ def _register_missing_builder_tools(server: PolicyAwareFastMCP) -> None:
32
32
  """Add current high-level builder tools to the unified MCP without duplicate names."""
33
33
  from .server_app_builder import build_builder_server
34
34
 
@@ -48,10 +48,10 @@ def _register_missing_builder_tools(server: FastMCP) -> None:
48
48
  )
49
49
 
50
50
 
51
- def build_server() -> FastMCP:
51
+ def build_server() -> PolicyAwareFastMCP:
52
52
  today = date.today()
53
53
  current_year = today.year
54
- server = FastMCP(
54
+ server = PolicyAwareFastMCP(
55
55
  "Qingflow MCP",
56
56
  instructions=f"""Use this unified server for Qingflow operational and builder workflows. Current date: `{today.isoformat()}`.
57
57
 
@@ -259,8 +259,14 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
259
259
  WorkflowTools(sessions, backend).register(server)
260
260
  ViewTools(sessions, backend).register(server)
261
261
  SolutionTools(sessions, backend).register(server)
262
+ # 保存补齐 Builder 前的真实注册来源,裸名冲突只能绑定最终保留 callable 的来源域。
263
+ legacy_tool_names = set(server._tool_manager._tools)
262
264
  _register_missing_builder_tools(server)
263
- return server
265
+ return configure_tool_policy(
266
+ server,
267
+ stdio_server_bindings(legacy_tool_names, server._tool_manager._tools),
268
+ source="environment",
269
+ )
264
270
 
265
271
 
266
272
  mcp = build_server()
@@ -2,8 +2,6 @@ from __future__ import annotations
2
2
 
3
3
  import json
4
4
 
5
- from mcp.server.fastmcp import FastMCP
6
-
7
5
  from .backend_client import BackendClient
8
6
  from .config import DEFAULT_PROFILE
9
7
  from .response_trim import BUILDER_SERVER_METHOD_MAP, trim_error_response, trim_public_response, wrap_trimmed_methods
@@ -14,6 +12,8 @@ from .tools.auth_tools import AuthTools
14
12
  from .tools.feedback_tools import FeedbackTools
15
13
  from .tools.file_tools import FileTools
16
14
  from .tools.workspace_tools import WorkspaceTools
15
+ from .tool_catalog import builder_server_bindings
16
+ from .tool_policy import PolicyAwareFastMCP, configure_tool_policy
17
17
 
18
18
 
19
19
  def _config_failure(message: str, *, fix_hint: str) -> dict:
@@ -27,8 +27,8 @@ def _config_failure(message: str, *, fix_hint: str) -> dict:
27
27
  }
28
28
 
29
29
 
30
- def build_builder_server() -> FastMCP:
31
- server = FastMCP(
30
+ def build_builder_server() -> PolicyAwareFastMCP:
31
+ server = PolicyAwareFastMCP(
32
32
  "Qingflow App Builder MCP",
33
33
  instructions=(
34
34
  "Use this server for AI-native Qingflow builder workflows. "
@@ -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 = "",
@@ -689,7 +718,11 @@ def build_builder_server() -> FastMCP:
689
718
  expected_package_id=expected_package_id,
690
719
  )
691
720
 
692
- return server
721
+ return configure_tool_policy(
722
+ server,
723
+ builder_server_bindings(server._tool_manager._tools),
724
+ source="environment",
725
+ )
693
726
 
694
727
 
695
728
  def main() -> None:
@@ -3,8 +3,6 @@ from __future__ import annotations
3
3
  import json
4
4
  from datetime import date
5
5
 
6
- from mcp.server.fastmcp import FastMCP
7
-
8
6
  from .backend_client import BackendClient
9
7
  from .config import DEFAULT_PROFILE
10
8
  from .response_trim import USER_SERVER_METHOD_MAP, trim_error_response, trim_public_response, wrap_trimmed_methods
@@ -22,12 +20,14 @@ from .tools.login_link_tools import LOGIN_LINK_DESCRIPTION, LoginLinkTools
22
20
  from .tools.resource_read_tools import ResourceReadTools
23
21
  from .tools.task_context_tools import TaskContextTools
24
22
  from .tools.workspace_tools import WorkspaceTools
23
+ from .tool_catalog import user_server_bindings
24
+ from .tool_policy import PolicyAwareFastMCP, configure_tool_policy
25
25
 
26
26
 
27
- def build_user_server(*, stateless_http: bool = False) -> FastMCP:
27
+ def build_user_server(*, stateless_http: bool = False) -> PolicyAwareFastMCP:
28
28
  today = date.today()
29
29
  current_year = today.year
30
- server = FastMCP(
30
+ server = PolicyAwareFastMCP(
31
31
  "Qingflow App User MCP",
32
32
  stateless_http=stateless_http,
33
33
  instructions=f"""Use this server for Qingflow operational workflows. Current date: `{today.isoformat()}`.
@@ -507,7 +507,11 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
507
507
  task_context_tools.register(server)
508
508
  directory_tools.register_frontend_search(server)
509
509
 
510
- return server
510
+ return configure_tool_policy(
511
+ server,
512
+ user_server_bindings(server._tool_manager._tools),
513
+ source="request" if stateless_http else "environment",
514
+ )
511
515
 
512
516
 
513
517
  mcp = build_user_server()
@@ -6,11 +6,15 @@ from typing import Any
6
6
 
7
7
  import anyio
8
8
  import uvicorn
9
- from mcp.server.fastmcp import FastMCP
10
-
11
9
  from .backend_client import BackendClient
12
10
  from .cloud_auth import CloudAuthBroker
13
- from .cloud_context import CloudMcpContext, current_call_platform, current_cloud_context
11
+ from .cloud_context import (
12
+ CloudMcpContext,
13
+ current_call_platform,
14
+ current_cloud_context,
15
+ current_http_tool_policy,
16
+ current_tool_policy_header,
17
+ )
14
18
  from .cloud_oauth_proxy import (
15
19
  CloudOAuthProxyConfig,
16
20
  OAuthAccessTokenResolver,
@@ -21,6 +25,8 @@ from .config import get_cloud_http_allowed_hosts, get_cloud_http_host, get_cloud
21
25
  from .errors import QingflowApiError, is_auth_like_error
22
26
  from .server_app_builder import build_builder_server
23
27
  from .server_app_user import build_user_server
28
+ from .tool_catalog import combined_server_bindings
29
+ from .tool_policy import PolicyAwareFastMCP, configure_tool_policy, parse_http_tool_policy
24
30
 
25
31
 
26
32
  BUILDER_TOOL_PREFIX = "builder_"
@@ -164,12 +170,18 @@ class CloudMcpAuthApp:
164
170
  cloud_context.token,
165
171
  )
166
172
 
173
+ tool_policy_header = _extract_header(scope, "x-qingflow-tool-policy")
174
+ http_tool_policy = parse_http_tool_policy(tool_policy_header, bytes(scope.get("query_string") or b""))
167
175
  context_token = current_cloud_context.set(cloud_context)
168
176
  call_platform_token = current_call_platform.set(call_platform)
177
+ tool_policy_token = current_tool_policy_header.set(tool_policy_header)
178
+ http_tool_policy_token = current_http_tool_policy.set(http_tool_policy)
169
179
  try:
170
180
  scope = _ensure_streamable_http_accept(scope)
171
181
  await self._app(scope, receive, send)
172
182
  finally:
183
+ current_http_tool_policy.reset(http_tool_policy_token)
184
+ current_tool_policy_header.reset(tool_policy_token)
173
185
  current_call_platform.reset(call_platform_token)
174
186
  current_cloud_context.reset(context_token)
175
187
 
@@ -397,16 +409,29 @@ def build_cloud_app() -> CloudMcpAuthApp:
397
409
  )
398
410
 
399
411
 
400
- def build_combined_server() -> FastMCP:
412
+ def build_combined_server() -> PolicyAwareFastMCP:
401
413
  server = build_user_server(stateless_http=True)
402
414
  builder_server = build_builder_server()
415
+ user_tool_names = set(server._tool_manager._tools)
416
+ builder_tool_names = set(builder_server._tool_manager._tools)
403
417
  server._mcp_server.name = "Qingflow Combined MCP"
404
418
  _register_prefixed_builder_tools(server, builder_server)
405
419
  _set_combined_instructions(server, builder_server)
406
- return server
420
+ return configure_tool_policy(
421
+ server,
422
+ combined_server_bindings(
423
+ user_tool_names,
424
+ builder_tool_names,
425
+ builder_prefix=BUILDER_TOOL_PREFIX,
426
+ ),
427
+ source="request",
428
+ )
407
429
 
408
430
 
409
- def _register_prefixed_builder_tools(target_server: FastMCP, builder_server: FastMCP) -> None:
431
+ def _register_prefixed_builder_tools(
432
+ target_server: PolicyAwareFastMCP,
433
+ builder_server: PolicyAwareFastMCP,
434
+ ) -> None:
410
435
  for original_name, tool in builder_server._tool_manager._tools.items():
411
436
  target_server._tool_manager.add_tool(
412
437
  tool.fn,
@@ -419,7 +444,10 @@ def _register_prefixed_builder_tools(target_server: FastMCP, builder_server: Fas
419
444
  )
420
445
 
421
446
 
422
- def _set_combined_instructions(user_server: FastMCP, builder_server: FastMCP) -> None:
447
+ def _set_combined_instructions(
448
+ user_server: PolicyAwareFastMCP,
449
+ builder_server: PolicyAwareFastMCP,
450
+ ) -> None:
423
451
  user_instructions = user_server.instructions or ""
424
452
  builder_instructions = builder_server.instructions or ""
425
453
  user_server._mcp_server.instructions = f"""Use this combined Qingflow MCP server for both user operational workflows and builder workflows.
@@ -454,6 +482,14 @@ def _extract_host(scope: dict[str, Any]) -> str:
454
482
  return ""
455
483
 
456
484
 
485
+ def _extract_header(scope: dict[str, Any], name: str) -> str | None:
486
+ expected = name.lower().encode("latin1")
487
+ for key, value in scope.get("headers", []):
488
+ if key.lower() == expected:
489
+ return value.decode("utf-8", errors="replace")
490
+ return None
491
+
492
+
457
493
  async def _read_request_body(
458
494
  receive: Callable[[], Awaitable[dict[str, Any]]],
459
495
  limit: int,
@@ -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: