@qingflow-tech/qingflow-app-builder-mcp 1.0.44 → 1.1.1

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -27,10 +27,6 @@ from ..builder_facade.models import (
     FieldPatch,
     FieldRemovePatch,
     FieldUpdatePatch,
-    FlowPreset,
-    FlowNodePatch,
-    FlowPlanRequest,
-    FlowTransitionPatch,
     LayoutApplyMode,
     LayoutPlanRequest,
     LayoutPreset,
@@ -70,7 +66,6 @@ from .qingbi_report_tools import QingbiReportTools
 from .role_tools import RoleTools
 from .solution_tools import SolutionTools
 from .view_tools import ViewTools
-from .workflow_tools import WorkflowTools
 
 
 def _normalize_builder_view_key(value: str) -> str:
@@ -80,7 +75,6 @@ def _normalize_builder_view_key(value: str) -> str:
     return raw
 
 
-PUBLIC_STABLE_FLOW_NODE_TYPES = ["start", "approve", "fill", "copy", "webhook", "end"]
 BUILDER_APPLY_SCHEMA_VERSION = "builder.apply.v1"
 BUILDER_APPLY_TOOL_NAMES = {
     "package_apply",
@@ -115,7 +109,6 @@ class AiBuilderTools(ToolBase):
             buttons=CustomButtonTools(sessions, backend),
             packages=PackageTools(sessions, backend),
             views=ViewTools(sessions, backend),
-            workflows=WorkflowTools(sessions, backend),
             portals=PortalTools(sessions, backend),
             charts=QingbiReportTools(sessions, backend),
             roles=RoleTools(sessions, backend),
@@ -455,22 +448,34 @@ class AiBuilderTools(ToolBase):
         ) -> JSONObject:
             return self.app_layout_apply(profile=profile, app_key=app_key, mode=mode, publish=publish, sections=sections or [])
 
+        @mcp.tool()
+        def app_flow_get(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            version_id: str = "",
+        ) -> JSONObject:
+            return self.app_get_flow(profile=profile, app_key=app_key, version_id=version_id or None)
+
+        @mcp.tool()
+        def app_flow_get_schema(profile: str = DEFAULT_PROFILE, schema_version: str = "") -> JSONObject:
+            return self.app_flow_get_schema(profile=profile, schema_version=schema_version or None)
+
         @mcp.tool()
         def app_flow_apply(
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
-            mode: str = "replace",
             publish: bool = True,
-            nodes: list[JSONObject] | None = None,
-            transitions: list[JSONObject] | None = None,
+            spec: JSONObject | None = None,
+            idempotency_key: str = "",
+            schema_version: str = "",
         ) -> JSONObject:
             return self.app_flow_apply(
                 profile=profile,
                 app_key=app_key,
-                mode=mode,
                 publish=publish,
-                nodes=nodes or [],
-                transitions=transitions or [],
+                spec=spec or {},
+                idempotency_key=idempotency_key or None,
+                schema_version=schema_version or None,
             )
 
         @mcp.tool()
@@ -1370,26 +1375,25 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_get_views", "arguments": {"profile": profile, "app_key": app_key}},
         )
 
-    @tool_cn_name("应用流程摘要读取")
-    def app_read_flow_summary(self, *, profile: str, app_key: str) -> JSONObject:
-        """执行应用相关逻辑。"""
-        normalized_args = {"app_key": app_key}
+    @tool_cn_name("Workflow Spec Schema")
+    def app_flow_get_schema(self, *, profile: str, schema_version: str | None = None) -> JSONObject:
+        normalized_args = {"schema_version": schema_version}
         return _safe_tool_call(
-            lambda: self._facade.app_read_flow_summary(profile=profile, app_key=app_key),
-            error_code="FLOW_READ_FAILED",
+            lambda: self._facade.flow_get_schema(profile=profile, schema_version=schema_version),
+            error_code="FLOW_SPEC_SCHEMA_FAILED",
             normalized_args=normalized_args,
-            suggested_next_call={"tool_name": "app_get_flow", "arguments": {"profile": profile, "app_key": app_key}},
+            suggested_next_call={"tool_name": "app_flow_get_schema", "arguments": {"profile": profile, **normalized_args}},
         )
 
-    @tool_cn_name("应用流程详情查询")
-    def app_get_flow(self, *, profile: str, app_key: str) -> JSONObject:
+    @tool_cn_name("Workflow Spec 读取")
+    def app_get_flow(self, *, profile: str, app_key: str, version_id: str | None = None) -> JSONObject:
         """执行应用相关逻辑。"""
-        normalized_args = {"app_key": app_key}
+        normalized_args = {"app_key": app_key, "version_id": version_id}
         return _safe_tool_call(
-            lambda: self._facade.app_get_flow(profile=profile, app_key=app_key),
+            lambda: self._facade.flow_get(profile=profile, app_key=app_key, version_id=version_id),
             error_code="APP_GET_FLOW_FAILED",
             normalized_args=normalized_args,
-            suggested_next_call={"tool_name": "app_get_flow", "arguments": {"profile": profile, "app_key": app_key}},
+            suggested_next_call={"tool_name": "app_flow_get", "arguments": {"profile": profile, "app_key": app_key}},
         )
 
     @tool_cn_name("应用图表摘要读取")
@@ -1600,52 +1604,6 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_layout_plan", "arguments": {"profile": profile, **normalized_request}},
         )
 
-    @tool_cn_name("应用流程规划")
-    def app_flow_plan(
-        self,
-        *,
-        profile: str,
-        app_key: str,
-        mode: str = "replace",
-        nodes: list[JSONObject] | None = None,
-        transitions: list[JSONObject] | None = None,
-        preset: str | None = None,
-    ) -> JSONObject:
-        """执行应用相关逻辑。"""
-        try:
-            request = FlowPlanRequest.model_validate(
-                {
-                    "app_key": app_key,
-                    "mode": mode,
-                    "nodes": nodes or [],
-                    "transitions": transitions or [],
-                    "preset": preset,
-                }
-            )
-        except ValidationError as exc:
-            return _validation_failure(
-                str(exc),
-                tool_name="app_flow_plan",
-                exc=exc,
-                suggested_next_call={
-                    "tool_name": "app_flow_plan",
-                    "arguments": {
-                        "profile": profile,
-                        "app_key": app_key,
-                        "mode": "replace",
-                        "preset": "basic_approval",
-                        "nodes": [],
-                        "transitions": [],
-                    },
-                },
-            )
-        return _safe_tool_call(
-            lambda: self._facade.app_flow_plan(profile=profile, request=request),
-            error_code="FLOW_PLAN_FAILED",
-            normalized_args=request.model_dump(mode="json"),
-            suggested_next_call={"tool_name": "app_flow_plan", "arguments": {"profile": profile, **request.model_dump(mode="json")}},
-        )
-
     @tool_cn_name("应用视图规划")
     def app_views_plan(
         self,
@@ -2376,111 +2334,51 @@ class AiBuilderTools(ToolBase):
         *,
         profile: str,
         app_key: str,
-        mode: str = "replace",
+        spec: JSONObject,
         publish: bool = True,
-        nodes: list[JSONObject],
-        transitions: list[JSONObject],
+        idempotency_key: str | None = None,
+        schema_version: str | None = None,
     ) -> JSONObject:
         """执行应用相关逻辑。"""
-        result = self._app_flow_apply_once(
-            profile=profile,
-            app_key=app_key,
-            mode=mode,
-            publish=publish,
-            nodes=nodes,
-            transitions=transitions,
-        )
-        result = self._retry_after_self_lock_release(
-            profile=profile,
-            result=result,
-            retry_call=lambda: self._app_flow_apply_once(
-                profile=profile,
-                app_key=app_key,
-                mode=mode,
-                publish=publish,
-                nodes=nodes,
-                transitions=transitions,
-            ),
-        )
-        return _attach_builder_apply_envelope("app_flow_apply", result)
-
-    def _app_flow_apply_once(
-        self,
-        *,
-        profile: str,
-        app_key: str,
-        mode: str = "replace",
-        publish: bool = True,
-        nodes: list[JSONObject],
-        transitions: list[JSONObject],
-    ) -> JSONObject:
-        """执行内部辅助逻辑。"""
-        plan_result = self._rewrite_plan_result_for_apply(
-            result=self.app_flow_plan(
-                profile=profile,
-                app_key=app_key,
-                mode=mode,
-                nodes=nodes,
-                transitions=transitions,
-                preset=None,
-            ),
-            profile=profile,
-            publish=publish,
-            plan_tool_name="app_flow_plan",
-            apply_tool_name="app_flow_apply",
-        )
-        if not isinstance(plan_result, dict) or plan_result.get("status") != "success":
-            return plan_result
-        plan_args = plan_result.get("normalized_args")
-        if not isinstance(plan_args, dict):
-            plan_args = {}
-        try:
-            request = FlowPlanRequest.model_validate(
-                {
-                    "app_key": plan_args.get("app_key") or app_key,
-                    "mode": plan_args.get("mode") or mode,
-                    "nodes": plan_args.get("nodes") or [],
-                    "transitions": plan_args.get("transitions") or [],
-                    "preset": None,
-                }
-            )
-        except ValidationError as exc:
-            return _validation_failure(
-                str(exc),
+        if not isinstance(spec, dict) or not spec:
+            return _config_failure(
                 tool_name="app_flow_apply",
-                exc=exc,
-                suggested_next_call={
-                    "tool_name": "app_flow_apply",
-                    "arguments": {
-                        "profile": profile,
-                        "app_key": str(plan_args.get("app_key") or app_key),
-                        "mode": str(plan_args.get("mode") or "replace"),
-                        "publish": publish,
-                        "nodes": plan_args.get("nodes") or [{"id": "start", "type": "start", "name": "发起"}],
-                        "transitions": plan_args.get("transitions") or [],
-                    },
-                },
+                message="app_flow_apply requires a non-empty WorkflowSpecDTO `spec` object.",
+                fix_hint="Call app_flow_get_schema, then app_flow_get for GET-first baseline, patch spec, and apply.",
             )
         normalized_args = {
-            "app_key": request.app_key,
-            "mode": request.mode,
+            "app_key": app_key,
             "publish": publish,
-            "nodes": [node.model_dump(mode="json") for node in request.nodes],
-            "transitions": [transition.model_dump(mode="json", by_alias=True) for transition in request.transitions],
+            "spec": spec,
+            "idempotency_key": idempotency_key,
+            "schema_version": schema_version,
         }
-        return _safe_tool_call(
-            lambda: self._facade.app_flow_apply(
+        result = _safe_tool_call(
+            lambda: self._facade.flow_apply(
                 profile=profile,
-                app_key=request.app_key,
-                mode=request.mode,
+                app_key=app_key,
+                spec=spec,
                 publish=publish,
-                nodes=[node.model_dump(mode="json") for node in request.nodes],
-                transitions=[transition.model_dump(mode="json", by_alias=True) for transition in request.transitions],
+                idempotency_key=idempotency_key,
+                schema_version=schema_version,
             ),
             error_code="FLOW_APPLY_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "app_flow_apply", "arguments": {"profile": profile, **normalized_args}},
         )
+        result = self._retry_after_self_lock_release(
+            profile=profile,
+            result=result,
+            retry_call=lambda: self._facade.flow_apply(
+                profile=profile,
+                app_key=app_key,
+                spec=spec,
+                publish=publish,
+                idempotency_key=idempotency_key,
+                schema_version=schema_version,
+            ),
+        )
+        return _attach_builder_apply_envelope("app_flow_apply", result)
 
     @tool_cn_name("应用视图应用")
     def app_views_apply(
@@ -5805,94 +5703,56 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "sections": [{"type": "paragraph", "paragraph_id": "basic", "title": "基础信息", "rows": [["项目名称", "项目负责人", "项目阶段", "优先级"]]}],
         },
     },
-    "app_flow_plan": {
-        "allowed_keys": ["app_key", "mode", "nodes", "transitions", "preset"],
-        "aliases": {
-            "overwrite": "replace",
-            "base_preset": "preset",
-            "default_approval": "basic_approval",
-            "node.role_names": "node.assignees.role_names",
-            "node.role_ids": "node.assignees.role_ids",
-            "node.member_names": "node.assignees.member_names",
-            "node.member_emails": "node.assignees.member_emails",
-            "node.member_uids": "node.assignees.member_uids",
-            "node.editable_fields": "node.permissions.editable_fields",
-            "default_approval": "basic_approval",
-        },
-        "allowed_values": {
-            "mode": ["replace"],
-            "preset": [member.value for member in FlowPreset],
-            "node.type": PUBLIC_STABLE_FLOW_NODE_TYPES,
-        },
-        "dependency_hints": [
-            "approval-style workflows require an explicit business status select field before app_flow_apply, such as 状态 / 处理状态 / 审批状态 / 工单状态",
-            "approve/fill/copy nodes require at least one assignee",
+    "app_flow_get_schema": {
+        "allowed_keys": ["schema_version"],
+        "aliases": {"schemaVersion": "schema_version"},
+        "allowed_values": {},
+        "execution_notes": [
+            "returns WorkflowSpec JSON Schema from /workflow/spec/schema",
+            "call this before authoring a new spec or validating spec shape",
+            "worksheet-level approval deduplication toggles (legacy global settings) are not yet part of WorkflowSpec",
         ],
+        "minimal_example": {
+            "profile": "default",
+            "schema_version": "vnext-2026-06",
+        },
+    },
+    "app_flow_get": {
+        "allowed_keys": ["app_key", "version_id"],
+        "aliases": {"versionId": "version_id"},
+        "allowed_values": {},
         "execution_notes": [
-            "public flow building is intentionally limited to linear workflows",
-            "branch and condition nodes are disabled because the backend workflow route is not front-end stable for these node types",
-            "do not create platform system workflow fields such as 当前流程状态 / 当前处理人 / 当前处理节点 / 流程标题; use an explicit business status field instead",
+            "returns current WorkflowSpecDTO for one app via GET /workflow/spec",
+            "use GET-first before patching and app_flow_apply",
         ],
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
-            "mode": "replace",
-            "preset": "basic_approval",
-            "nodes": [
-                {
-                    "id": "approve_1",
-                    "type": "approve",
-                    "name": "部门审批",
-                    "assignees": {"role_names": ["项目经理"]},
-                    "permissions": {"editable_fields": ["状态", "审批意见"]},
-                }
-            ],
-            "transitions": [],
         },
     },
     "app_flow_apply": {
-        "allowed_keys": ["app_key", "mode", "publish", "nodes", "transitions"],
+        "allowed_keys": ["app_key", "publish", "spec", "idempotency_key", "schema_version"],
         "aliases": {
-            "overwrite": "replace",
-            "node.role_names": "node.assignees.role_names",
-            "node.role_ids": "node.assignees.role_ids",
-            "node.member_names": "node.assignees.member_names",
-            "node.member_emails": "node.assignees.member_emails",
-            "node.member_uids": "node.assignees.member_uids",
-            "node.editable_fields": "node.permissions.editable_fields",
-        },
-        "allowed_values": {
-            "mode": ["replace"],
-            "node.type": PUBLIC_STABLE_FLOW_NODE_TYPES,
+            "schemaVersion": "schema_version",
+            "idempotencyKey": "idempotency_key",
         },
+        "allowed_values": {},
         "dependency_hints": [
-            "approval-style workflows require an explicit business status select field before app_flow_apply, such as 状态 / 处理状态 / 审批状态 / 工单状态",
-            "approve/fill/copy nodes require at least one assignee",
+            "spec must be a complete WorkflowSpecDTO object (replace-only apply)",
         ],
         "execution_notes": [
-            "public flow building is intentionally limited to linear workflows",
-            "app_flow_apply is replace-only; do not treat node snippets as partial patches",
-            "branch and condition nodes are disabled because the backend workflow route is not front-end stable for these node types",
-            "do not create platform system workflow fields such as 当前流程状态 / 当前处理人 / 当前处理节点 / 流程标题; use an explicit business status field instead",
-            "workflow verification only covers linear node structure in the public tool surface",
+            "posts to /workflow/spec:apply with appKey, idempotencyKey, schemaVersion, and spec",
+            "verification uses appliedSpec, diffSummary, and semanticLint from the apply response",
+            "publish=false keeps changes in draft when supported by the backend",
         ],
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
-            "mode": "replace",
             "publish": True,
-            "nodes": [
-                {"id": "start", "type": "start", "name": "发起"},
-                {
-                    "id": "approve_1",
-                    "type": "approve",
-                    "name": "部门审批",
-                    "assignees": {"role_names": ["项目经理"]},
-                    "permissions": {"editable_fields": ["状态", "审批意见"]},
-                },
-                {"id": "end", "type": "end", "name": "结束"},
-            ],
-            "transitions": [{"from": "start", "to": "approve_1"}, {"from": "approve_1", "to": "end"}],
+            "spec": {
+                "nodes": [{"id": "n1", "type": "APPLICANT", "name": "发起"}],
+                "transitions": [],
+            },
         },
     },
     "app_views_plan": {
@@ -6242,8 +6102,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "aliases": {},
         "allowed_values": {},
         "execution_notes": [
-            "returns workflow configuration summary for one app",
-            "use this before app_flow_apply when you need the current node structure",
+            "returns WorkflowSpecDTO for one app (alias of app_flow_get)",
+            "use app_flow_get_schema then app_flow_get before app_flow_apply",
         ],
         "minimal_example": {
             "profile": "default",
@@ -6549,7 +6409,6 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
 _PRIVATE_BUILDER_TOOL_CONTRACTS = {
     "app_schema_plan",
     "app_layout_plan",
-    "app_flow_plan",
     "app_views_plan",
 }
 

package/src/qingflow_mcp/tools/solution_tools.py

@@ -38,7 +38,6 @@ from .qingbi_report_tools import QingbiReportTools
 from .record_tools import RecordTools
 from .role_tools import RoleTools
 from .view_tools import ViewTools
-from .workflow_tools import WorkflowTools
 from .workspace_tools import WorkspaceTools
 
 STAGED_BUILD_MODES = {"preflight", "plan", "apply", "repair"}
@@ -737,6 +736,36 @@ class SolutionTools(ToolBase):
     ) -> dict[str, Any]:
         """执行方案相关逻辑。"""
         mode = _normalize_staged_build_mode(mode)
+        app_key = str(flow_spec.get("app_key") or "").strip()
+        spec_payload = flow_spec.get("spec")
+        if app_key and isinstance(spec_payload, dict) and spec_payload:
+            from .ai_builder_tools import AiBuilderTools
+
+            builder = AiBuilderTools(self.sessions, self.backend)
+            if mode in {"preflight", "plan"}:
+                return {
+                    "build_id": build_id or _generate_build_id(run_label=run_label, stage_name="flow"),
+                    "mode": mode,
+                    "stage": "flow",
+                    "status": "planned" if mode == "plan" else "preflighted",
+                    "normalized_args": {"app_key": app_key, "spec": spec_payload},
+                    "tool_name": "solution_build_flow",
+                }
+            result = builder.app_flow_apply(
+                profile=profile,
+                app_key=app_key,
+                spec=spec_payload,
+                publish=publish,
+                schema_version=flow_spec.get("schema_version") or flow_spec.get("schemaVersion"),
+            )
+            return {
+                "build_id": build_id,
+                "mode": mode,
+                "stage": "flow",
+                "status": result.get("status"),
+                "result": result,
+                "tool_name": "solution_build_flow",
+            }
         return self._stage_build(
             profile=profile,
             mode=mode,
@@ -1409,7 +1438,6 @@ class SolutionTools(ToolBase):
             role_tools=RoleTools(self.sessions, self.backend),
             app_tools=AppTools(self.sessions, self.backend),
             record_tools=RecordTools(self.sessions, self.backend),
-            workflow_tools=WorkflowTools(self.sessions, self.backend),
             view_tools=ViewTools(self.sessions, self.backend),
             chart_tools=QingbiReportTools(self.sessions, self.backend),
             portal_tools=PortalTools(self.sessions, self.backend),

package/src/qingflow_mcp/tools/workflow_tools.py

@@ -14,25 +14,13 @@ class WorkflowTools(ToolBase):
 
     类型：流程配置工具。
     主要职责：
-    1. 查询流程节点与流程图配置；
-    2. 读取与更新流程规则；
-    3. 支持流程发布与流程调试辅助能力。
+    1. 支持流程运行时校验与调试辅助能力；
+    2. 保留 legacy 节点写路径供内部/测试直接调用（非 MCP 公开）。
+    设计期流程配置读取统一走 WorkflowSpec（app_flow_get / GET /api/workflow/spec）。
     """
 
     def register(self, mcp: FastMCP) -> None:
         """注册当前工具到 MCP 服务。"""
-        @mcp.tool()
-        def workflow_list_nodes(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
-            return self.workflow_list_nodes(profile=profile, app_key=app_key)
-
-        @mcp.tool()
-        def workflow_get_node_detail(profile: str = DEFAULT_PROFILE, app_key: str = "", audit_node_id: int = 0) -> JSONObject:
-            return self.workflow_get_node_detail(profile=profile, app_key=app_key, audit_node_id=audit_node_id)
-
-        @mcp.tool()
-        def workflow_get_global_settings(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
-            return self.workflow_get_global_settings(profile=profile, app_key=app_key)
-
         @mcp.tool()
         def workflow_get_future_nodes(profile: str = DEFAULT_PROFILE, app_key: str = "", apply_id: int = 0) -> JSONObject:
             return self.workflow_get_future_nodes(profile=profile, app_key=app_key, apply_id=apply_id)
@@ -53,22 +41,6 @@ class WorkflowTools(ToolBase):
                 audit_node_id=audit_node_id,
             )
 
-        @mcp.tool()
-        def workflow_get_qsource_active(profile: str = DEFAULT_PROFILE, app_key: str = "", qsource_id: int = 0) -> JSONObject:
-            return self.workflow_get_qsource_active(profile=profile, app_key=app_key, qsource_id=qsource_id)
-
-        @mcp.tool()
-        def workflow_get_qsource_passive(profile: str = DEFAULT_PROFILE, app_key: str = "", qsource_id: int = 0) -> JSONObject:
-            return self.workflow_get_qsource_passive(profile=profile, app_key=app_key, qsource_id=qsource_id)
-
-        @mcp.tool()
-        def workflow_get_editable_question_ids(profile: str = DEFAULT_PROFILE, app_key: str = "", audit_node_id: int = 0) -> JSONObject:
-            return self.workflow_get_editable_question_ids(profile=profile, app_key=app_key, audit_node_id=audit_node_id)
-
-        @mcp.tool()
-        def workflow_get_print_nodes(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
-            return self.workflow_get_print_nodes(profile=profile, app_key=app_key)
-
     @tool_cn_name("流程节点列表")
     def workflow_list_nodes(self, *, profile: str, app_key: str) -> JSONObject:
         """执行流程相关逻辑。"""