@qingflow-tech/qingflow-cli 1.1.33 → 1.1.35

package/skills/qingflow-cli/scripts/workflow/validate_flow_spec.py

@@ -300,6 +300,25 @@ def check_orphan_nodes(nodes, edges):
     return errors
 
 
+def check_routing_entry_and_sync(nodes, edges):
+    """检查入口出边和需要继续流转节点的 sync 标记。"""
+    errors = []
+    outgoing = {}
+    for edge in edges:
+        outgoing.setdefault(edge.get('from'), []).append(edge.get('to'))
+
+    for node in nodes:
+        node_id = node.get('id')
+        node_type = node.get('type')
+        node_label = f"节点 {node_id} ({node.get('name','')})"
+        has_outgoing = bool(outgoing.get(node_id))
+        if node_type == 'applicant' and not has_outgoing:
+            errors.append(f"申请人入口节点 {node_id} 没有出边，提交后流程不会进入下一节点")
+        if has_outgoing and node.get('sync') is not True:
+            errors.append(f"{node_label} 存在出边但未显式 sync=true，后端可能停止继续路由")
+    return errors
+
+
 def check_minimal_modification(old_spec, new_spec):
     """更新模式下检查最小修改原则：ID 稳定性、无冗余删建、修改范围合理"""
     warnings = []
@@ -560,7 +579,10 @@ def main():
         # 11. 孤立节点检查
         all_errors.extend(check_orphan_nodes(nodes, edges))
 
-    # 12. 更新模式：最小修改原则检查
+        # 12. 入口出边与 sync 检查
+        all_errors.extend(check_routing_entry_and_sync(nodes, edges))
+
+    # 13. 更新模式：最小修改原则检查
     if previous_file:
         try:
             prev_spec = load_json(previous_file)
@@ -602,4 +624,4 @@ def main():
 
 
 if __name__ == '__main__':
-    main()
+    main()

package/src/qingflow_mcp/builder_facade/service.py

@@ -8733,7 +8733,7 @@ class AiBuilderFacade:
         if unsupported_nodes:
             return _failed(
                 "FLOW_NODE_TYPE_UNSUPPORTED",
-                "legacy nodes/transitions input supports only simple linear workflows; use app_flow_get_schema/app_flow_get and app_flow_apply with spec for branching or richer WorkflowSpec graphs.",
+                "public workflow writes use app_flow_get_schema/app_flow_get and app_flow_apply with WorkflowSpec spec; legacy nodes/transitions input cannot express this graph.",
                 normalized_args={
                     "app_key": request.app_key,
                     "mode": str(request.mode or "replace"),
@@ -10624,7 +10624,7 @@ class AiBuilderFacade:
             flow_compile_ms += _duration_ms(flow_compile_started_at)
             return finish(_failed(
                 "FLOW_NODE_TYPE_UNSUPPORTED",
-                "legacy nodes/transitions input supports only simple linear workflows; use app_flow_get_schema/app_flow_get and app_flow_apply with spec for branching or richer WorkflowSpec graphs.",
+                "public workflow writes use app_flow_get_schema/app_flow_get and app_flow_apply with WorkflowSpec spec; legacy nodes/transitions input cannot express this graph.",
                 normalized_args=normalized_args,
                 details={
                     "unsupported_nodes": unsupported_nodes,
@@ -14848,7 +14848,14 @@ class AiBuilderFacade:
         include_error: bool = False,
     ) -> tuple[Any, bool] | tuple[Any, bool, QingflowApiError | None]:
         try:
-            workflow = self.workflows.workflow_list_nodes(profile=profile, app_key=app_key)
+            workflow = self._with_backend_context(
+                profile,
+                lambda context: workflow_spec_api.fetch_spec(
+                    self.apps.backend,
+                    context,
+                    app_key=app_key,
+                ),
+            )
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
             if tolerate_404 and (
@@ -14857,7 +14864,7 @@ class AiBuilderFacade:
             ):
                 return ([], True, api_error) if include_error else ([], True)
             raise
-        result = workflow.get("result")
+        result = workflow if _looks_like_workflow_spec_payload(workflow) else []
         return (result, False, None) if include_error else (result, False)
 
     def _load_app_state(self, *, profile: str, app_key: str) -> dict[str, Any]:
@@ -25013,6 +25020,27 @@ def _apply_row_widths(row: list[dict[str, Any]]) -> None:
 
 def _summarize_workflow_nodes(result: Any) -> list[dict[str, Any]]:
     nodes = []
+    spec: Any = result
+    if isinstance(result, dict) and isinstance(result.get("spec"), dict):
+        spec = result.get("spec")
+    if isinstance(spec, dict) and isinstance(spec.get("nodes"), list):
+        for item in spec.get("nodes") or []:
+            if not isinstance(item, dict):
+                continue
+            node_id = item.get("id")
+            name = item.get("name") or item.get("title")
+            if node_id is None or not name:
+                continue
+            attrs = item.get("attrs") if isinstance(item.get("attrs"), dict) else {}
+            nodes.append(
+                {
+                    "id": str(node_id),
+                    "name": name,
+                    "type": item.get("type"),
+                    **({"sub_type": attrs.get("subType")} if attrs.get("subType") else {}),
+                }
+            )
+        return nodes
     if isinstance(result, dict):
         iterable = result.values()
     elif isinstance(result, list):
@@ -25030,6 +25058,15 @@ def _summarize_workflow_nodes(result: Any) -> list[dict[str, Any]]:
     return nodes
 
 
+def _looks_like_workflow_spec_payload(payload: Any) -> bool:
+    if not isinstance(payload, dict):
+        return False
+    spec = payload.get("spec")
+    if isinstance(spec, dict):
+        return True
+    return any(key in payload for key in ("nodes", "edges", "transitions", "schemaVersion"))
+
+
 def _workflow_node_iterable(result: Any) -> list[dict[str, Any]]:
     if isinstance(result, dict):
         iterable = result.values()

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

@@ -255,10 +255,10 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
 
     flow_apply_apply = flow_apply_subparsers.add_parser("apply", help="执行流程变更")
     flow_apply_apply.add_argument("--app-key", required=True)
-    flow_apply_apply.add_argument("--mode", choices=["replace"], default="replace")
+    flow_apply_apply.add_argument("--mode", choices=["replace"], default="replace", help=argparse.SUPPRESS)
     flow_apply_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=True)
-    flow_apply_apply.add_argument("--nodes-file")
-    flow_apply_apply.add_argument("--transitions-file")
+    flow_apply_apply.add_argument("--nodes-file", help=argparse.SUPPRESS)
+    flow_apply_apply.add_argument("--transitions-file", help=argparse.SUPPRESS)
     flow_apply_apply.add_argument("--spec-file")
     flow_apply_apply.add_argument("--patch-nodes-file", help="节点局部更新 JSON 数组，每项含 id + set/unset")
     flow_apply_apply.add_argument("--idempotency-key", default="")
@@ -855,11 +855,18 @@ def _handle_flow_apply(args: argparse.Namespace, context: CliContext) -> dict:
     patch_nodes = load_list_arg(getattr(args, "patch_nodes_file", None), option_name="--patch-nodes-file")
     spec = load_object_arg(getattr(args, "spec_file", None), option_name="--spec-file")
     has_legacy_nodes = bool(getattr(args, "nodes_file", None) or getattr(args, "transitions_file", None))
+    if has_legacy_nodes:
+        raise_config_error(
+            "builder flow apply no longer exposes legacy --nodes-file/--transitions-file input.",
+            fix_hint="Use --spec-file for a complete WorkflowSpec, or --patch-nodes-file for targeted edits after builder flow get.",
+            error_code="FLOW_LEGACY_INPUT_DISABLED",
+            details={"allowed_input_modes": ["--spec-file", "--patch-nodes-file"]},
+        )
     selected_modes = sum(1 for selected in (bool(patch_nodes), bool(spec), has_legacy_nodes) if selected)
     if selected_modes != 1:
         raise_config_error(
-            "builder flow apply requires exactly one input mode: --spec-file, --patch-nodes-file, or --nodes-file with --transitions-file.",
-            fix_hint="Use --patch-nodes-file for local edits, --spec-file for full WorkflowSpec, or legacy --nodes-file plus --transitions-file.",
+            "builder flow apply requires exactly one input mode: --spec-file or --patch-nodes-file.",
+            fix_hint="Use --spec-file for a complete WorkflowSpec, or --patch-nodes-file for targeted edits after builder flow get.",
         )
     if patch_nodes:
         return context.builder.app_flow_apply(
@@ -879,18 +886,9 @@ def _handle_flow_apply(args: argparse.Namespace, context: CliContext) -> dict:
             idempotency_key=args.idempotency_key,
             schema_version=args.schema_version,
         )
-    if not getattr(args, "nodes_file", None) or not getattr(args, "transitions_file", None):
-        raise_config_error(
-            "legacy builder flow apply requires both --nodes-file and --transitions-file.",
-            fix_hint="Pass both files, or use --spec-file / --patch-nodes-file.",
-        )
-    return context.builder.app_flow_apply(
-        profile=args.profile,
-        app_key=args.app_key,
-        mode=args.mode,
-        publish=bool(args.publish),
-        nodes=require_list_arg(args.nodes_file, option_name="--nodes-file"),
-        transitions=require_list_arg(args.transitions_file, option_name="--transitions-file"),
+    raise_config_error(
+        "builder flow apply requires --spec-file or --patch-nodes-file.",
+        fix_hint="Use --spec-file for a complete WorkflowSpec, or --patch-nodes-file for targeted edits after builder flow get.",
     )
 
 

package/src/qingflow_mcp/server_app_builder.py

@@ -52,7 +52,7 @@ def build_builder_server() -> FastMCP:
             "For associated reports/views, use app_associated_resources_apply for both the app-level associated_resources pool and per-view display config; associated_item_id is the app-level form_asos_chart.id, and view_configs/remove/reorder may also pass an existing resource's chart_id/chart_key/view_key because the tool resolves those to the internal id. Before creating an associated resource, read app_get.associated_resources and reuse an existing matching target_app_key + view_key/chart_key through patch_resources; client_key only works inside one apply call and is not persisted. Do not ask agents to pass backend raw sourceType: views infer the internal Qingflow view source, reports default to BI app reports, and dataset reports use report_source=dataset. "
             "For code_block fields with output bindings, always use qf_output assignment rather than const/let qf_output, and use app_repair_code_blocks when an existing form hangs because output-bound fields stay loading. "
             "Use package_apply to manage package metadata, visibility, grouping, and ordering, and app_publish_verify for explicit final publish verification. "
-            "For workflow edits, use app_flow_get_schema/app_flow_get when raw WorkflowSpec shape is needed, then app_flow_apply with spec for full replacement or patch_nodes for targeted node edits; the legacy nodes/transitions path is only for simple linear start/approve/fill/copy/webhook/end flows. Declare node assignees and editable fields explicitly. "
+            "For workflow edits, use app_flow_get_schema/app_flow_get when raw WorkflowSpec shape is needed, then app_flow_apply with spec for full replacement or patch_nodes for targeted node edits. Declare node assignees and editable fields explicitly. "
             "If builder writes are blocked by the current user's own edit lock, use app_release_edit_lock_if_mine with the lock owner details from the failed result. "
             "Do not handcraft internal solution payloads or rely on build_id/stage/repair. "
             "If the current MCP capability is unsupported, the workflow is awkward, or the user's need still cannot be satisfied after reasonable use, first summarize the gap, ask whether to submit feedback, and call feedback_submit only after explicit user confirmation."
@@ -513,10 +513,7 @@ def build_builder_server() -> FastMCP:
     def app_flow_apply(
         profile: str = DEFAULT_PROFILE,
         app_key: str = "",
-        mode: str = "replace",
         publish: bool = True,
-        nodes: list[dict] | None = None,
-        transitions: list[dict] | None = None,
         spec: dict | None = None,
         idempotency_key: str = "",
         schema_version: str = "",
@@ -525,10 +522,7 @@ def build_builder_server() -> FastMCP:
         return ai_builder.app_flow_apply(
             profile=profile,
             app_key=app_key,
-            mode=mode,
             publish=publish,
-            nodes=nodes or [],
-            transitions=transitions or [],
             spec=spec,
             idempotency_key=idempotency_key or None,
             schema_version=schema_version or None,

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -720,10 +720,7 @@ class AiBuilderTools(ToolBase):
         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 = "",
@@ -732,10 +729,7 @@ class AiBuilderTools(ToolBase):
             return self.app_flow_apply(
                 profile=profile,
                 app_key=app_key,
-                mode=mode,
                 publish=publish,
-                nodes=nodes or [],
-                transitions=transitions or [],
                 spec=spec,
                 idempotency_key=idempotency_key or None,
                 schema_version=schema_version or None,
@@ -3573,7 +3567,7 @@ class AiBuilderTools(ToolBase):
         *,
         profile: str,
         app_key: str,
-        mode: str = "replace",
+        mode: str | None = None,
         publish: bool = True,
         nodes: list[JSONObject] | None = None,
         transitions: list[JSONObject] | None = None,
@@ -3625,29 +3619,37 @@ class AiBuilderTools(ToolBase):
                 normalized_args=normalized_args,
                 suggested_next_call={"tool_name": "app_flow_get", "arguments": {"profile": profile, "app_key": app_key}},
             ))
-        effective_nodes = nodes or []
-        effective_transitions = transitions or []
-        result = self._app_flow_apply_once(
-            profile=profile,
-            app_key=app_key,
-            mode=mode,
-            publish=publish,
-            nodes=effective_nodes,
-            transitions=effective_transitions,
-        )
-        result = self._retry_after_self_lock_release(
-            profile=profile,
-            result=result,
-            retry_call=lambda: self._app_flow_apply_once(
+        if nodes or transitions:
+            effective_nodes = nodes or []
+            effective_transitions = transitions or []
+            result = self._app_flow_apply_once(
                 profile=profile,
                 app_key=app_key,
-                mode=mode,
+                mode=mode or "replace",
                 publish=publish,
                 nodes=effective_nodes,
                 transitions=effective_transitions,
-            ),
-        )
-        return _attach_builder_apply_envelope("app_flow_apply", result)
+            )
+            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 or "replace",
+                    publish=publish,
+                    nodes=effective_nodes,
+                    transitions=effective_transitions,
+                ),
+            )
+            return _attach_builder_apply_envelope("app_flow_apply", result)
+        normalized_args = {"app_key": app_key, "publish": publish}
+        return _attach_builder_apply_envelope("app_flow_apply", _failed(
+            "FLOW_SPEC_OR_PATCH_REQUIRED",
+            "app_flow_apply requires spec for a complete WorkflowSpec write or patch_nodes for targeted edits.",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_flow_get_schema", "arguments": {"profile": profile}},
+        ))
 
     def _app_flow_apply_once(
         self,
@@ -7731,7 +7733,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "approve/fill/copy nodes require at least one assignee",
         ],
         "execution_notes": [
-            "app_flow_plan is a legacy helper for linear public node aliases; use app_flow_get/app_flow_get_schema plus app_flow_apply spec or patch_nodes for the full WorkflowSpec path",
+            "app_flow_plan is private compatibility plumbing, not an agent-facing workflow path; use app_flow_get/app_flow_get_schema plus app_flow_apply spec or patch_nodes",
             "do not create platform system workflow fields such as 当前流程状态 / 当前处理人 / 当前处理节点 / 流程标题; use an explicit business status field instead",
         ],
         "minimal_example": {
@@ -7759,35 +7761,22 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "patch_nodes",
             "idempotency_key",
             "schema_version",
-            "mode",
-            "nodes",
-            "transitions",
         ],
         "aliases": {
-            "overwrite": "replace",
             "patchNodes": "patch_nodes",
             "idempotencyKey": "idempotency_key",
             "schemaVersion": "schema_version",
-            "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,
         },
+        "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",
+            "WorkflowSpec nodes should declare sync=true for routing nodes and explicit assignees for approval/filling/cc nodes",
         ],
         "execution_notes": [
             "preferred full workflow path is app_flow_get_schema/app_flow_get -> app_flow_apply with spec",
             "use patch_nodes for targeted existing-node edits; each item uses id plus set/unset",
-            "legacy nodes/transitions remains available for simple linear start/approve/fill/copy/webhook/end flows only",
-            "do not mix spec, patch_nodes, and legacy nodes/transitions in one call",
+            "public workflow writes use only spec or patch_nodes",
+            "do not mix spec and patch_nodes in one call",
             "do not create platform system workflow fields such as 当前流程状态 / 当前处理人 / 当前处理节点 / 流程标题; use an explicit business status field instead",
             "workflow readback is app_flow_get; use app_flow_get_schema when raw spec shape is unclear",
         ],
@@ -7803,14 +7792,6 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "publish": True,
             "patch_nodes": [{"id": "approve_1", "set": {"name": "主管审批"}}],
         },
-        "legacy_linear_example": {
-            "profile": "default",
-            "app_key": "APP_KEY",
-            "mode": "replace",
-            "publish": True,
-            "nodes": [{"id": "start", "type": "start", "name": "发起"}, {"id": "end", "type": "end", "name": "结束"}],
-            "transitions": [{"from": "start", "to": "end"}],
-        },
     },
     "app_views_plan": {
         "allowed_keys": [