@qingflow-tech/qingflow-cli 1.1.61-beta.1 → 1.1.61-beta.3

package/README.md

@@ -7,7 +7,7 @@ Qingflow CLI 是轻流面向开发者和 AI Agent 的命令行工具。它把轻
 ## 安装
 
 ```bash
-npm install @qingflow-tech/qingflow-cli@1.1.61-beta.1
+npm install @qingflow-tech/qingflow-cli@1.1.61-beta.3
 ```
 
 推荐从官网复制这一条一键安装 Qingflow CLI：
@@ -21,7 +21,7 @@ npx qingflow-cli@latest install
 ## 运行
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-cli@1.1.61-beta.1 qingflow
+npx -y -p @qingflow-tech/qingflow-cli@1.1.61-beta.3 qingflow
 ```
 
 全局安装后可以直接运行：
@@ -62,7 +62,7 @@ qingflow-skills install --agent codex --scope user
 如果你通过一次性 `npx -p` 执行 skills 安装，建议加 `--copy`，避免 symlink 指向 npm 临时执行缓存：
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-cli@1.1.61-beta.1 qingflow-skills install --agent codex --scope user --copy
+npx -y -p @qingflow-tech/qingflow-cli@1.1.61-beta.3 qingflow-skills install --agent codex --scope user --copy
 ```
 
 `qingflow-skills install` 默认使用 symlink，且遇到同名 skill 不会覆盖；只有显式传入 `--force` 才会替换。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-cli",
-  "version": "1.1.61-beta.1",
+  "version": "1.1.61-beta.3",
   "description": "Human-friendly Qingflow command line interface for auth, record operations, import, tasks, and stable builder flows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "1.1.61b1"
+version = "1.1.61b3"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/skills/qingflow-cli/SKILL.md

@@ -23,7 +23,7 @@ description: |
 | [reference/00-INDEX.md](./reference/00-INDEX.md) | **总导航**：按用户目标选择 record / task / builder 文档；复杂任务先读 |
 | [reference/QINGFLOW_CLI_MEMBER_CHEATSHEET.md](./reference/core/QINGFLOW_CLI_MEMBER_CHEATSHEET.md)     | **普通成员**主线：最短路径、`view_id`、与管理命令的差异预期                                                                                                                                                                                                                                                  |
 | [reference/QINGFLOW_CLI_FIELD_DATA_TYPES.md](./reference/core/QINGFLOW_CLI_FIELD_DATA_TYPES.md)       | **字段数据类型**：`record schema …` 的 `fields[]`（`field_id`、`title`、`kind`、`options`…）；`record list/get/access` 与写入 payload 的形态对照                                                                                                                                                                    |
-| [reference/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./reference/core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md) | **应用记录获取数据**：`app get`（`accessible_views`）→ `record schema browse` → `record list(query)` 模糊定位 / `record get` 详情页首屏上下文 / `record logs` 全量日志；分析取数转 `record_access`                                                                                                                                                                        |
+| [reference/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./reference/core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md) | **普通应用数据读取**：`data query` 获取记录和 schema → 按需 `data get` 读取单条；附件下载见 [data 操作说明](./reference/data/README.md) |
 | [reference/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md](./reference/task/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md) | **任务(待办已办)上下文 SOP**：`task list` → `task get` → `task log` → `task report` → `task action`；只把 `task_id` 作为主定位参数                                                                                               |
 | [reference/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md) | **批量导入 SOP**：`app_get`（**`import_capability`**）→ `record_import_template_get` → `record_import_verify` →（可选）`record_import_repair_local` → `record_import_start` → `record_import_status_get`；CLI `import` / `record schema import`                                                   |
 | [reference/builder/README.md](./reference/builder/README.md) | **Builder 总导航**：完整系统、单应用、字段、布局、视图、报表、门户、按钮/关联资源、流程、发布校验 |
@@ -40,7 +40,7 @@ description: |
 | [reference/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md) | **新建记录**：`record schema insert -> record insert --items-file`；成员/部门/关联优先自然语言输入；细节见 [record/insert](./reference/record/insert/README.md) |
 | [reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md) | **更新记录**：主链路是 `record get` → 智能体按 `fields[]` 组 key/value → **`record update`**；`record schema update` 仅用于失败后诊断可写字段/路径                                                                                                                                 |
 | [reference/QINGFLOW_CLI_RECORD_DELETE_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_DELETE_WORKFLOW.md) | **删除记录**：`record list/get` 精确定位 → `record delete --app-key --record-id --view-id system:*`；批量用 `--record-ids-file` |
-| [reference/record/analysis/README.md](./reference/record/analysis/README.md) | **数据分析**：最终统计结论、分析报告、趋势/排名/比例/分布统一走 `record access -> Python/pandas` |
+| [reference/record/analysis/README.md](./reference/record/analysis/README.md) | **数据分析**：最终统计结论、分析报告、趋势/排名/比例/分布统一走 `data query --all --output csv -> Python/pandas` |
 | [reference/builder/reference/app-delivery-sop.md](./reference/builder/reference/app-delivery-sop.md) | **底层交付参考**：历史完整 SOP、权限、系统列和工具细节；不是主入口 |
 | [reference/builder/reference/workspace-icons.md](./reference/builder/reference/workspace-icons.md) | **图标参考**：`builder icon catalog`；新建应用包、应用、门户必须显式选择非 `template` 的 `icon + color` |
 | [reference/builder/reference/match-rules.md](./reference/builder/reference/match-rules.md) | **统一筛选 / 条件写法**：`filters`、`visible_when`、QingBI 图表筛选、工作流条件、`match_mappings`、`field_mappings` 的 `operator/value` 规则 |
@@ -129,18 +129,11 @@ qingflow --json data query --app-key APP_KEY > tmp/qingflow_data_query.json
 
 ---
 
-## 应用记录：获取数据工作流（推荐闭环）
+## 应用数据：查询与读取（默认路径）
 
-与常见 **编排/API 文档**里的命名对齐时的固定顺序为：
+已知 `app_key` 时直接执行 `qingflow --json data query --app-key <APP_KEY>`；首次查询保留默认 schema，根据响应中的 `field_capabilities` 和 `hints` 决定筛选、分页或停止。定位到 `record_id` 后，按需执行 `qingflow --json data get --app-key <APP_KEY> --record-id <RECORD_ID>`；下载附件时加 `--download-attachments`。
 
-1. **`app_get`**：`qingflow --json app get --app-key <APP_KEY>` → 在 **`data.accessible_views`**（或等价路径）选取 **`view_id`**。
-2. **`record_schema_get`（`schema_mode=browse`）**：`qingflow --json record schema browse --app-key <APP_KEY> --view-id <VIEW_ID>`（CLI 子命令 **`browse`** 即浏览视图表结构）。
-3. **`record_list` / `record_get` / `record_logs_get`**：`record list …` 用于样本浏览或模糊定位候选；`record get --record-id …` 下钻单条前端详情页首屏上下文（字段、首屏日志、引用、图片与文件资产）；只有需要完整审计历史时，再用 `record logs --record-id …` 读取全量数据日志和流程日志 JSONL。
-
-`app get` 里的 `CUSTOM_VIEW_LIST_UNAVAILABLE` 表示自定义视图列表读取被权限或后端限制降级；若 `accessible_views` 中仍有 `system:*`，可继续用该视图读数。若没有任何视图，再回到前端 URL、`app list` 可见应用、或用户提供的 `viewgraphKey` 补充上下文，不要直接断言应用不可读。
-`app get.data.can_create=false` 才表示 applicant/create 路径不可用；创建权限探测遇到 auth / server 等非权限类错误时应直接按失败处理，不要包装成“未知创建权限”或“用户无新建权限”。
-
-**细则、响应解包、`view_id` 雷区与命令模板**见 **[reference/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./reference/core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**（编写前已对当前 CLI **实跑**校验）。若仅需「最快看一眼有没有行」，可省略 **`schema browse`**，直接走下文「最短路径」。如果用户要任何最终统计结论、分析报告、趋势/排名/比例/分布，按 **[record/analysis](./reference/record/analysis/README.md)** 执行 `record access -> Python/pandas`。
+参数与附件处理见 [data 操作说明](./reference/data/README.md)。详情页引用、关联资源和完整日志见 [record 专项参考](./reference/record/QINGFLOW_CLI_RECORD_SPECIALIZED_WORKFLOW.md)；最终统计结论按 [数据分析说明](./reference/record/analysis/README.md) 使用 `data query --all --output csv`。
 
 ---
 
@@ -167,7 +160,7 @@ qingflow --json data query --app-key APP_KEY > tmp/qingflow_data_query.json
 
 **更新路径**：`record update` 会自动先尝试数据管理员直改，再 fallback 到前端同源的 custom view 详情编辑路径；如果当前用户存在这条记录的唯一待办且目标字段在当前节点可编辑，最后会尝试 workflow save-only。成功时只需要读 **`status / update_route / verification_status`**；失败时再读失败原因与路线诊断。不要把中间 route 或辅助 schema/readback 探测的 40002 / 40027 / 404 当作最终失败。
 
-**大号 `record_id`（常见于 Snowflake 类 id）**：若干 CLI 版本在 **`record update` 写入路径**上对 `apply_id` 会做 **JavaScript 安全整数**相关校验，`list`/`get`/`schema update` 仍可能正常而 **更新落库报错**（常为 `apply_id must be positive`）。排障见 **[reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**。业务统计与最终结论仍必须按 **[record/analysis](./reference/record/analysis/README.md)** 使用 `record access -> Python/pandas`。
+**大号 `record_id`（常见于 Snowflake 类 id）**：若干 CLI 版本在 **`record update` 写入路径**上对 `apply_id` 会做 **JavaScript 安全整数**相关校验，`list`/`get`/`schema update` 仍可能正常而 **更新落库报错**（常为 `apply_id must be positive`）。排障见 **[reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**。业务统计与最终结论仍必须按 **[record/analysis](./reference/record/analysis/README.md)** 使用 `data query --all --output csv -> Python/pandas`。
 
 **命令模板、批量 `items` 形态、与新建相同的写入值约定**（按 **`kind`** 分题型见 **[QINGFLOW_CLI_FIELD_DATA_TYPES.md](./reference/core/QINGFLOW_CLI_FIELD_DATA_TYPES.md)**）见 **[reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./reference/record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**。
 
@@ -242,16 +235,16 @@ qingflow --json data query \
 
 - `data insert/update/delete` 是普通应用数据直接写入入口。写入前用只读 `data query/get` 获取 schema、字段能力与访问范围；删除、覆盖已有值、批量写入或其他不可逆操作必须先确认目标和影响范围。
 - `task`、builder、import 均按路由表进入专项文档；主 Skill 不复制其参数、枚举或完整 SOP。
-- 导出／下载只有用户明确需要文件时才使用，并按对应命令要求提供视图上下文；不要把导出当作普通查询或统计分析默认入口。
+- 导出／下载只有用户明确需要文件时才使用，并按对应命令的参数执行；不要把导出当作普通查询或统计分析默认入口。
 - 查看视图时，`baseInfo` 或 `viewConfig` 只有 40002 / 40027 / 404 这类权限/缺失边界可用另一侧降级，非权限类后端错误不隐藏；完整规则见 Builder 视图文档。
 
-## record 专项
+## 专项上下文
 
-`record` 用于详情页专项上下文、完整数据／流程日志、代码块字段执行，以及用户指定的 `record` 操作。普通记录附件下载使用 `data get --download-attachments`。
+详情页引用、关联资源、完整数据／流程日志或代码块字段执行见 [record 专项参考](./reference/record/QINGFLOW_CLI_RECORD_SPECIALIZED_WORKFLOW.md)。用户明确指定 `record` 命令时，阅读对应的 `reference/record/` 文档。
 
-`data query/get` 默认只读取附件字段。用户需要下载或读取附件时，保持相同 profile 和工作区，对已定位的同一 `app_key`、`record_id` 执行 `qingflow --json data get --download-attachments`，保留 schema，并使用 `file_assets.items[].local_path`。该入口直接处理存储 Cookie、重定向和数据面链接刷新，无需 view_id 或 record get。不要用 curl、requests 或 urllib 直接请求远端 Qingflow 附件 URL，也不要为下载而读取认证配置或打印 token。
+`data query/get` 默认只读取附件字段。用户需要下载或读取附件时，保持相同 profile 和工作区，对已定位的同一 `app_key`、`record_id` 执行 `qingflow --json data get --download-attachments`，保留 schema，并使用 `file_assets.items[].local_path`。该入口直接处理存储 Cookie、重定向和数据面链接刷新。不要用 curl、requests 或 urllib 直接请求远端 Qingflow 附件 URL，也不要为下载而读取认证配置或打印 token。
 
-普通应用数据使用 `data`。不得改用 `record list/access/get/insert/update/delete` 绕过 data 返回的权限、字段能力或校验结果。附件下载阅读 [data 附件下载](./reference/data/README.md#附件下载与读取)；完整日志和详情页专项上下文阅读 [record 专项参考](./reference/record/QINGFLOW_CLI_RECORD_SPECIALIZED_WORKFLOW.md)。`record delete` 提交不要传 `custom:*`、`list_type`，细则见 [record 删除参考](./reference/record/QINGFLOW_CLI_RECORD_DELETE_WORKFLOW.md)。
+附件下载阅读 [data 附件下载](./reference/data/README.md#附件下载与读取)。
 
 ## 关联入口
 

package/skills/qingflow-cli/reference/core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md

@@ -14,7 +14,7 @@ data query（默认带 schema）
   → 已知 record_id 时按需 data get
 ```
 
-已知 `app_key` 时直接 query；未知时只做必要的 `app list --query`。不要先执行 `app get → record schema browse`，普通数据查询也不需要 `view_id`。
+已知 `app_key` 时直接 query；未知时先用 `app list --query` 定位应用。
 
 ## 1. 首次查询与字段能力
 
@@ -33,7 +33,7 @@ qingflow --json data query --app-key APP_KEY \
 - `access`：本次实际访问范围；
 - `hints`：需要收窄、继续、停止或调整参数的动态提示。
 
-不要用 insert/update 探测字段能力，也不要从 record schema 推断 data 能力。
+不要用 insert/update 探测字段能力。
 
 ## 2. 字段筛选
 
@@ -96,7 +96,7 @@ qingflow --json data get --app-key APP_KEY --record-id RECORD_ID \
   > tmp/qingflow_data_get.json
 ```
 
-`data get` 默认只读取业务字段。需要下载或读取附件时，对同一 `app_key`、`record_id` 加 `--download-attachments`，保留 schema，并读取 `file_assets.items[].local_path`；无需 view_id 或 record get。不要用 Python/curl 直接请求远端附件 URL。状态、预算与完整流程见 [附件下载与读取](../data/README.md#附件下载与读取)；完整日志按 record 专项执行。
+`data get` 默认只读取业务字段。需要下载或读取附件时，对同一 `app_key`、`record_id` 加 `--download-attachments`，保留 schema，并读取 `file_assets.items[].local_path`。不要用 Python/curl 直接请求远端附件 URL。状态、预算与完整流程见 [附件下载与读取](../data/README.md#附件下载与读取)；完整日志按 record 专项执行。
 
 ## 6. 统计分析
 

package/src/qingflow_mcp/cli/main.py

@@ -7,11 +7,22 @@ import sys
 from typing import Any, Callable, TextIO
 
 from ..errors import QingflowApiError, backend_code_value_int, message_looks_like_invalid_token
-from ..public_surface import cli_public_tool_spec_from_namespace
+from ..public_surface import (
+    NON_TOOL_CLI_HANDLER_ROUTES,
+    cli_public_tool_spec_from_namespace,
+    cli_route_from_namespace,
+    cli_trim_key_from_namespace,
+)
 from ..resource_uri import cli_resource_base_url
 from ..response_trim import resolve_cli_tool_name, trim_error_response, trim_public_response
 from ..tools.ai_builder_tools import _attach_builder_apply_envelope
 from ..version import get_cli_version, get_cli_version_info
+from ..tool_policy import (
+    TOOL_POLICY_ENV,
+    TOOL_POLICY_INVALID,
+    ToolPolicyViolation,
+    parse_tool_policy,
+)
 from .context import CliContext, build_cli_context
 from .formatters import emit_json_result, emit_text_result
 from .commands import register_all_commands
@@ -90,6 +101,14 @@ def run(
     if handler is None:
         parser.print_help(out)
         return 2
+    violation = _cli_tool_policy_violation(args)
+    if violation is not None:
+        return _emit_error(
+            violation.payload(),
+            json_mode=bool(args.json),
+            stdout=out,
+            stderr=err,
+        )
     try:
         if _should_force_json_output(args):
             setattr(args, "json", True)
@@ -122,6 +141,20 @@ def run(
     return exit_code
 
 
+def _cli_tool_policy_violation(args: argparse.Namespace) -> ToolPolicyViolation | None:
+    stable_id = cli_trim_key_from_namespace(args)
+    if stable_id is None:
+        # 仅显式登记的非业务分发器可跳过闸门；无子命令的新增 handler 也必须默认拒绝。
+        if cli_route_from_namespace(args) in NON_TOOL_CLI_HANDLER_ROUTES:
+            return None
+        return ToolPolicyViolation(
+            TOOL_POLICY_INVALID,
+            "user:unregistered",
+            "CLI 业务命令未登记稳定工具 ID",
+        )
+    return parse_tool_policy(os.getenv(TOOL_POLICY_ENV)).violation_for(stable_id)
+
+
 def _handle_version(_args: argparse.Namespace, _context: CliContext) -> dict[str, Any]:
     info = get_cli_version_info()
     return {

package/src/qingflow_mcp/cloud_context.py

@@ -2,11 +2,14 @@ from __future__ import annotations
 
 from contextvars import ContextVar
 from dataclasses import dataclass, field
-from typing import Callable
+from typing import TYPE_CHECKING, Callable
 
 from .backend_client import BackendRequestContext
 from .session_store import BackendSession, SessionProfile
 
+if TYPE_CHECKING:
+    from .tool_policy import ToolPolicySnapshot
+
 
 CLOUD_PROFILE_NAME = "__cloud_mcp__"
 
@@ -73,3 +76,15 @@ current_call_platform: ContextVar[str] = ContextVar(
     "qingflow_mcp_current_call_platform",
     default="",
 )
+
+# 远端 MCP 每个 HTTP 请求独立绑定策略原文；缺头用 None 表示，不回退进程环境变量。
+current_tool_policy_header: ContextVar[str | None] = ContextVar(
+    "qingflow_mcp_current_tool_policy_header",
+    default=None,
+)
+
+# 在 HTTP 入口合成一次快照，列表与调用共用，避免将 URL 选择保存到会话或共享环境。
+current_http_tool_policy: ContextVar[ToolPolicySnapshot | None] = ContextVar(
+    "qingflow_mcp_current_http_tool_policy",
+    default=None,
+)

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/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()}`.
 
@@ -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()}`.
@@ -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,