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

package/src/qingflow_mcp/public_surface.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import argparse
 from argparse import Namespace
 from dataclasses import dataclass
 
@@ -109,6 +110,7 @@ USER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
     PublicToolSpec(USER_DOMAIN, "record_export_direct", ("record_export_direct",), ("export", "direct"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "record_code_block_run", ("record_code_block_run",), ("record", "code-block-run"), cli_show_effective_context=True, cli_context_write=True),
     PublicToolSpec(USER_DOMAIN, "task_list", ("task_list",), ("task", "list"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "task_workbench", cli_route=("task",), mcp_public=False),
     PublicToolSpec(USER_DOMAIN, "task_get", ("task_get",), ("task", "get"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "task_action_execute", ("task_action_execute",), ("task", "action"), cli_show_effective_context=True, cli_context_write=True),
     PublicToolSpec(
@@ -130,12 +132,12 @@ USER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
 
 
 BUILDER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
-    PublicToolSpec(BUILDER_DOMAIN, "auth_use_credential", ("auth_use_credential",), ("builder", "auth", "use-credential"), cli_public=False),
-    PublicToolSpec(BUILDER_DOMAIN, "auth_whoami", ("auth_whoami",), ("builder", "auth", "whoami"), cli_public=False),
-    PublicToolSpec(BUILDER_DOMAIN, "auth_logout", ("auth_logout",), ("builder", "auth", "logout"), cli_public=False),
+    PublicToolSpec(BUILDER_DOMAIN, "auth_use_credential", ("auth_use_credential",), cli_public=False),
+    PublicToolSpec(BUILDER_DOMAIN, "auth_whoami", ("auth_whoami",), cli_public=False),
+    PublicToolSpec(BUILDER_DOMAIN, "auth_logout", ("auth_logout",), cli_public=False),
     PublicToolSpec(BUILDER_DOMAIN, "get_login_link", ("get_login_link",), mcp_public=True, cli_public=False),
-    PublicToolSpec(BUILDER_DOMAIN, "workspace_list", ("workspace_list",), ("builder", "workspace", "list"), cli_public=False),
-    PublicToolSpec(BUILDER_DOMAIN, "workspace_get", ("workspace_get",), ("builder", "workspace", "get"), cli_public=False),
+    PublicToolSpec(BUILDER_DOMAIN, "workspace_list", ("workspace_list",), cli_public=False),
+    PublicToolSpec(BUILDER_DOMAIN, "workspace_get", ("workspace_get",), cli_public=False),
     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),
     PublicToolSpec(BUILDER_DOMAIN, "feedback_submit", ("feedback_submit",), ("builder", "feedback", "submit"), has_contract=True),
     PublicToolSpec(BUILDER_DOMAIN, "builder_tool_contract", ("builder_tool_contract",), ("builder", "contract"), has_contract=False),
@@ -194,7 +196,8 @@ PUBLIC_TOOL_BY_KEY: dict[str, PublicToolSpec] = {spec.trim_key: spec for spec in
 PUBLIC_TOOL_BY_CLI_ROUTE: dict[tuple[str, ...], PublicToolSpec] = {
     spec.cli_route: spec
     for spec in ALL_PUBLIC_TOOL_SPECS
-    if spec.cli_public and spec.cli_route is not None
+    # 隐藏命令仍有可达 handler，闸门绑定不能把“帮助不可见”误当成“不可执行”。
+    if spec.cli_route is not None
 }
 PUBLIC_TOOL_BY_CLI_ROUTE.update(
     {
@@ -205,6 +208,9 @@ PUBLIC_TOOL_BY_CLI_ROUTE.update(
     }
 )
 
+# 这些 handler 只负责版本输出或参数迁移提示，不会发起轻流业务请求。
+NON_TOOL_CLI_HANDLER_ROUTES = frozenset({("version",), ("record", "schema")})
+
 
 def public_tool_specs(domain: str | None = None) -> tuple[PublicToolSpec, ...]:
     if domain is None:
@@ -258,11 +264,13 @@ def cli_route_from_namespace(args: Namespace) -> tuple[str, ...] | None:
         record_command = getattr(args, "record_command", None)
         if record_command == "schema":
             schema_command = getattr(args, "record_schema_command", None)
-            return (command, "schema", schema_command) if isinstance(schema_command, str) and schema_command else None
+            if isinstance(schema_command, str) and schema_command:
+                return (command, "schema", schema_command)
+            return (command, "schema")
         return (command, record_command) if isinstance(record_command, str) and record_command else None
     if command == "task":
         task_command = getattr(args, "task_command", None)
-        return (command, task_command) if isinstance(task_command, str) and task_command else None
+        return (command, task_command) if isinstance(task_command, str) and task_command else (command,)
     if command != "builder":
         child_attr = f"{command}_command"
         child = getattr(args, child_attr, None)
@@ -283,3 +291,54 @@ def cli_route_from_namespace(args: Namespace) -> tuple[str, ...] | None:
     child_attr = f"builder_{builder_command.replace('-', '_')}_command"
     child = getattr(args, child_attr, None)
     return ("builder", builder_command, child) if isinstance(child, str) and child else None
+
+
+def discover_cli_handler_routes(
+    parser: argparse.ArgumentParser,
+) -> dict[tuple[str, ...], tuple[str, ...]]:
+    """从 argparse 实际 handler 树枚举规范化路由及其实现，包含中间交互入口。"""
+    discovered: dict[tuple[str, ...], set[str]] = {}
+
+    def walk(current: argparse.ArgumentParser, path: tuple[str, ...], inherited: dict[str, object]) -> None:
+        attrs = dict(inherited)
+        for action in current._actions:
+            if isinstance(action, argparse._SubParsersAction):
+                continue
+            if action.dest != argparse.SUPPRESS and action.default != argparse.SUPPRESS:
+                attrs.setdefault(action.dest, action.default)
+        attrs.update(current._defaults)
+
+        handler = current._defaults.get("handler")
+        if callable(handler):
+            variants = [attrs]
+            for action in current._actions:
+                if isinstance(action, argparse._SubParsersAction) or action.choices is None:
+                    continue
+                variants.extend({**attrs, action.dest: choice} for choice in action.choices)
+            for variant in variants:
+                route = cli_route_from_namespace(Namespace(**variant))
+                if route is None:
+                    route = _normalize_cli_parser_path(path)
+                if route:
+                    identity = f"{handler.__module__}:{handler.__qualname__}"
+                    discovered.setdefault(route, set()).add(identity)
+
+        for action in current._actions:
+            if not isinstance(action, argparse._SubParsersAction):
+                continue
+            for name, child in action.choices.items():
+                next_attrs = dict(attrs)
+                next_attrs[action.dest] = name
+                walk(child, path + (name,), next_attrs)
+
+    walk(parser, (), {})
+    return {route: tuple(sorted(handlers)) for route, handlers in discovered.items()}
+
+
+def _normalize_cli_parser_path(path: tuple[str, ...]) -> tuple[str, ...]:
+    normalized = list(path)
+    if normalized and normalized[0] == "build":
+        normalized[0] = "builder"
+    if len(normalized) > 1 and normalized[0] == "builder" and normalized[1] == "associated-resources":
+        normalized[1] = "associated-resource"
+    return tuple(normalized)

package/src/qingflow_mcp/response_trim.py

@@ -51,8 +51,9 @@ COMMON_ERROR_DROP_TOP = {
 
 SUCCESS_POLICY_BY_TOOL: dict[str, TransformFn] = {}
 
-#: 这两个校验命令的产出契约明确包含 ok 字段（供阶段 2 SKILL.md 引用），
+#: 这些校验命令的产出契约明确包含 ok 字段（供阶段 2 SKILL.md 引用），
 #: 需在 success 裁剪时保留 ok（默认 COMMON_SUCCESS_DROP_TOP 会丢弃 ok）。
+#: `builder:app_views_validate`（views 声明式校验）同属校验类工具，ok 同样进产出契约。
 _KEEP_OK_TOOLS = {
     "builder:app_form_validate_formula",
     "builder:app_form_validate_code_block",

package/src/qingflow_mcp/server.py

@@ -2,8 +2,6 @@ from __future__ import annotations
 
 from datetime import date
 
-from mcp.server.fastmcp import FastMCP
-
 from .backend_client import BackendClient
 from .session_store import SessionStore
 from .tools.app_tools import AppTools
@@ -26,9 +24,11 @@ from .tools.task_context_tools import TaskContextTools
 from .tools.view_tools import ViewTools
 from .tools.workflow_tools import WorkflowTools
 from .tools.workspace_tools import WorkspaceTools
+from .tool_catalog import stdio_server_bindings
+from .tool_policy import PolicyAwareFastMCP, configure_tool_policy
 
 
-def _register_missing_builder_tools(server: FastMCP) -> None:
+def _register_missing_builder_tools(server: PolicyAwareFastMCP) -> None:
     """Add current high-level builder tools to the unified MCP without duplicate names."""
     from .server_app_builder import build_builder_server
 
@@ -48,10 +48,10 @@ def _register_missing_builder_tools(server: FastMCP) -> None:
         )
 
 
-def build_server() -> FastMCP:
+def build_server() -> PolicyAwareFastMCP:
     today = date.today()
     current_year = today.year
-    server = FastMCP(
+    server = PolicyAwareFastMCP(
         "Qingflow MCP",
         instructions=f"""Use this unified server for Qingflow operational and builder workflows. Current date: `{today.isoformat()}`.
 
@@ -149,7 +149,7 @@ Analysis answers must include concrete numbers. When applicable, include percent
 - `record_delete` deletes by `record_id` or `record_ids`, and requires an accessible system `view_id`; use custom views only to locate records, not as the delete route.
 - `record_get` is the single-record frontend detail context tool. It returns detail-page visible fields, one-level relation targets, first-page data/workflow logs, associated views/reports, local readable image assets, local downloadable file assets, unavailable context, and `semantic_context`.
 - Use `record_logs_get` only when the user needs the full visible data/workflow log history for a specific record. It writes JSONL files locally and returns file paths plus completeness metadata; do not expect full log arrays in the response.
-- Read record images from `record_get.media_assets.items[].local_path` when `readable_by_agent=true`; read attachments/documents/tables from `record_get.file_assets.items[].local_path` and `extraction.text_path` when present. `record_get` follows the frontend storage cookie redirect path for Qingflow attachments, and remote file URLs should not be treated as directly readable.
+- Download record attachments with `data_get(download_attachments=true, include_schema=true)` for the same app and record; use `file_assets.items[].local_path` only when `access_status=downloaded`. This includes original images and videos. Inspect `file_assets.warnings` for partial failures; do not request remote private URLs or fall back to record/detail tools after a data-plane denial. For specialized detail-page context, read `record_get` rich-text images from `media_assets` and its files from `file_assets` local paths or `extraction.text_path` when present.
 - `record_get.columns` are focus hints only; they do not project the detail fields. Read facts from top-level `fields[]`.
 - When readback shape matters after insert or update, prefer `record_get` for human/detail-page context, or `record_list(..., output_profile="normalized")` for batch-shaped normalized rows.
 
@@ -259,8 +259,14 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
     WorkflowTools(sessions, backend).register(server)
     ViewTools(sessions, backend).register(server)
     SolutionTools(sessions, backend).register(server)
+    # 保存补齐 Builder 前的真实注册来源，裸名冲突只能绑定最终保留 callable 的来源域。
+    legacy_tool_names = set(server._tool_manager._tools)
     _register_missing_builder_tools(server)
-    return server
+    return configure_tool_policy(
+        server,
+        stdio_server_bindings(legacy_tool_names, server._tool_manager._tools),
+        source="environment",
+    )
 
 
 mcp = build_server()

package/src/qingflow_mcp/server_app_builder.py

@@ -2,8 +2,6 @@ from __future__ import annotations
 
 import json
 
-from mcp.server.fastmcp import FastMCP
-
 from .backend_client import BackendClient
 from .config import DEFAULT_PROFILE
 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
 from .tools.feedback_tools import FeedbackTools
 from .tools.file_tools import FileTools
 from .tools.workspace_tools import WorkspaceTools
+from .tool_catalog import builder_server_bindings
+from .tool_policy import PolicyAwareFastMCP, configure_tool_policy
 
 
 def _config_failure(message: str, *, fix_hint: str) -> dict:
@@ -27,8 +27,8 @@ def _config_failure(message: str, *, fix_hint: str) -> dict:
     }
 
 
-def build_builder_server() -> FastMCP:
-    server = FastMCP(
+def build_builder_server() -> PolicyAwareFastMCP:
+    server = PolicyAwareFastMCP(
         "Qingflow App Builder MCP",
         instructions=(
             "Use this server for AI-native Qingflow builder workflows. "
@@ -689,7 +689,11 @@ def build_builder_server() -> FastMCP:
             expected_package_id=expected_package_id,
         )
 
-    return server
+    return configure_tool_policy(
+        server,
+        builder_server_bindings(server._tool_manager._tools),
+        source="environment",
+    )
 
 
 def main() -> None:

package/src/qingflow_mcp/server_app_user.py

@@ -3,8 +3,6 @@ from __future__ import annotations
 import json
 from datetime import date
 
-from mcp.server.fastmcp import FastMCP
-
 from .backend_client import BackendClient
 from .config import DEFAULT_PROFILE
 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
 from .tools.resource_read_tools import ResourceReadTools
 from .tools.task_context_tools import TaskContextTools
 from .tools.workspace_tools import WorkspaceTools
+from .tool_catalog import user_server_bindings
+from .tool_policy import PolicyAwareFastMCP, configure_tool_policy
 
 
-def build_user_server(*, stateless_http: bool = False) -> FastMCP:
+def build_user_server(*, stateless_http: bool = False) -> PolicyAwareFastMCP:
     today = date.today()
     current_year = today.year
-    server = FastMCP(
+    server = PolicyAwareFastMCP(
         "Qingflow App User MCP",
         stateless_http=stateless_http,
         instructions=f"""Use this server for Qingflow operational workflows. Current date: `{today.isoformat()}`.
@@ -144,7 +144,7 @@ Analysis answers must include concrete numbers. When applicable, include percent
 - `record_delete` deletes by `record_id` or `record_ids`, and requires an accessible system `view_id`; use custom views only to locate records, not as the delete route.
 - `record_get` is the single-record frontend detail context tool. It returns detail-page visible fields, one-level relation targets, first-page data/workflow logs, associated views/reports, local readable image assets, local downloadable file assets, unavailable context, and `semantic_context`.
 - Use `record_logs_get` only when the user needs the full visible data/workflow log history for a specific record. It writes JSONL files locally and returns file paths plus completeness metadata; do not expect full log arrays in the response.
-- Read record images from `record_get.media_assets.items[].local_path` when `readable_by_agent=true`; read attachments/documents/tables from `record_get.file_assets.items[].local_path` and `extraction.text_path` when present. `record_get` follows the frontend storage cookie redirect path for Qingflow attachments, and remote file URLs should not be treated as directly readable.
+- Download record attachments with `data_get(download_attachments=true, include_schema=true)` for the same app and record; use `file_assets.items[].local_path` only when `access_status=downloaded`. This includes original images and videos. Inspect `file_assets.warnings` for partial failures; do not request remote private URLs or fall back to record/detail tools after a data-plane denial. For specialized detail-page context, read `record_get` rich-text images from `media_assets` and its files from `file_assets` local paths or `extraction.text_path` when present.
 - `record_get.columns` are focus hints only; they do not project the detail fields. Read facts from top-level `fields[]`.
 - When readback shape matters after insert or update, prefer `record_get` for human/detail-page context, or `record_list(..., output_profile="normalized")` for batch-shaped normalized rows.
 
@@ -507,7 +507,11 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
     task_context_tools.register(server)
     directory_tools.register_frontend_search(server)
 
-    return server
+    return configure_tool_policy(
+        server,
+        user_server_bindings(server._tool_manager._tools),
+        source="request" if stateless_http else "environment",
+    )
 
 
 mcp = build_user_server()

package/src/qingflow_mcp/server_cloud.py

@@ -6,11 +6,15 @@ from typing import Any
 
 import anyio
 import uvicorn
-from mcp.server.fastmcp import FastMCP
-
 from .backend_client import BackendClient
 from .cloud_auth import CloudAuthBroker
-from .cloud_context import CloudMcpContext, current_call_platform, current_cloud_context
+from .cloud_context import (
+    CloudMcpContext,
+    current_call_platform,
+    current_cloud_context,
+    current_http_tool_policy,
+    current_tool_policy_header,
+)
 from .cloud_oauth_proxy import (
     CloudOAuthProxyConfig,
     OAuthAccessTokenResolver,
@@ -21,6 +25,8 @@ from .config import get_cloud_http_allowed_hosts, get_cloud_http_host, get_cloud
 from .errors import QingflowApiError, is_auth_like_error
 from .server_app_builder import build_builder_server
 from .server_app_user import build_user_server
+from .tool_catalog import combined_server_bindings
+from .tool_policy import PolicyAwareFastMCP, configure_tool_policy, parse_http_tool_policy
 
 
 BUILDER_TOOL_PREFIX = "builder_"
@@ -164,12 +170,18 @@ class CloudMcpAuthApp:
                 cloud_context.token,
             )
 
+        tool_policy_header = _extract_header(scope, "x-qingflow-tool-policy")
+        http_tool_policy = parse_http_tool_policy(tool_policy_header, bytes(scope.get("query_string") or b""))
         context_token = current_cloud_context.set(cloud_context)
         call_platform_token = current_call_platform.set(call_platform)
+        tool_policy_token = current_tool_policy_header.set(tool_policy_header)
+        http_tool_policy_token = current_http_tool_policy.set(http_tool_policy)
         try:
             scope = _ensure_streamable_http_accept(scope)
             await self._app(scope, receive, send)
         finally:
+            current_http_tool_policy.reset(http_tool_policy_token)
+            current_tool_policy_header.reset(tool_policy_token)
             current_call_platform.reset(call_platform_token)
             current_cloud_context.reset(context_token)
 
@@ -397,16 +409,29 @@ def build_cloud_app() -> CloudMcpAuthApp:
     )
 
 
-def build_combined_server() -> FastMCP:
+def build_combined_server() -> PolicyAwareFastMCP:
     server = build_user_server(stateless_http=True)
     builder_server = build_builder_server()
+    user_tool_names = set(server._tool_manager._tools)
+    builder_tool_names = set(builder_server._tool_manager._tools)
     server._mcp_server.name = "Qingflow Combined MCP"
     _register_prefixed_builder_tools(server, builder_server)
     _set_combined_instructions(server, builder_server)
-    return server
+    return configure_tool_policy(
+        server,
+        combined_server_bindings(
+            user_tool_names,
+            builder_tool_names,
+            builder_prefix=BUILDER_TOOL_PREFIX,
+        ),
+        source="request",
+    )
 
 
-def _register_prefixed_builder_tools(target_server: FastMCP, builder_server: FastMCP) -> None:
+def _register_prefixed_builder_tools(
+    target_server: PolicyAwareFastMCP,
+    builder_server: PolicyAwareFastMCP,
+) -> None:
     for original_name, tool in builder_server._tool_manager._tools.items():
         target_server._tool_manager.add_tool(
             tool.fn,
@@ -419,7 +444,10 @@ def _register_prefixed_builder_tools(target_server: FastMCP, builder_server: Fas
         )
 
 
-def _set_combined_instructions(user_server: FastMCP, builder_server: FastMCP) -> None:
+def _set_combined_instructions(
+    user_server: PolicyAwareFastMCP,
+    builder_server: PolicyAwareFastMCP,
+) -> None:
     user_instructions = user_server.instructions or ""
     builder_instructions = builder_server.instructions or ""
     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:
     return ""
 
 
+def _extract_header(scope: dict[str, Any], name: str) -> str | None:
+    expected = name.lower().encode("latin1")
+    for key, value in scope.get("headers", []):
+        if key.lower() == expected:
+            return value.decode("utf-8", errors="replace")
+    return None
+
+
 async def _read_request_body(
     receive: Callable[[], Awaitable[dict[str, Any]]],
     limit: int,