Skip to content

JiuwenSwarm is an intelligent AI Agent built on openJiuwen. It extends the powerful capabilities of large language models directly to your fingertips through various communication apps you use daily.

Python

fix(common): 连接器请求级发现失败时目录工具标明本轮不可用,避免反复查询触发熔断(OA.05000090)

zhangfuzhiac114c2b02f2
diff --git a/jiuwenswarm/common/docs/specs/S_09_mcp-integration.md b/jiuwenswarm/common/docs/specs/S_09_mcp-integration.md
index e9f8ca2c92..d11dc084f5 100644
--- a/jiuwenswarm/common/docs/specs/S_09_mcp-integration.md
+++ b/jiuwenswarm/common/docs/specs/S_09_mcp-integration.md
@@ -7,7 +7,7 @@
| 类型 | spec |
| 编号 / slug | S_09 / mcp-integration |
| 关联模块 | jiuwenswarm/common/{mcp_config, mcp_server_registry, mcp_call_timeout_patch, mcp_tool_list_refresh_patch}.py |
-| 最近一次修订日期 | 2026-10-29 |
+| 最近一次修订日期 | 2026-10-30 |
| 关联 feature | F_01_deepresearch-mcp-delegation.md |
## 范围 / 边界
@@ -93,6 +93,14 @@ mcp_tool_list_refresh_patch.py ┘ 唯一装配点:interface_deep.DeepAdapter.
工具的深拷贝,不发现工具、不启动 worker。返回值包含未脱敏连接凭据,仅供进程内授权
检查,不得写日志、持久化或直接传给 SDK。研究专用端点调用原请求级工具,每次 list/call
重验当前请求、来源身份、工具集合和权限;恢复仅保留首次来源与当前授权的交集。
+- **N11 请求级连接器加载结果对模型可见**:`list_request_mcp_server_tools` 以空
+ connect_params 表示发现失败,非空 params + 零工具表示合法零工具(如 tool_filter 全关)。
+ `interface_deep._append_request_mcp_server_tools` 按此区分并记录本请求未加载出工具的连接器
+ (名称 → 原因),在发布前写到本请求的宿主 MCP 工具实例上;宿主的两个连接器目录工具
+ (列出连接器 / 查询单个连接器的工具)结果末尾追加"本轮不可调用"说明
+ (`annotate_connector_catalog_result`)。状态只挂在本请求工具实例上,不跨请求、不影响其他连接器。
+ 目录工具名与查询参数名以宿主 MCP 服务的工具定义为准;查询单个连接器时取不到查询名,
+ 按列出连接器的语义全量标注,避免参数名变化后静默失效。
## 接口契约
@@ -100,6 +108,7 @@ mcp_tool_list_refresh_patch.py ┘ 唯一装配点:interface_deep.DeepAdapter.
|---|---|---|
| `mcp_config.py` | `create_mcp_tool` / `build_mcp_server_config` / `build_enabled_mcp_server_configs` / `acquire_request_scoped_mcp_session` / `RequestScopedOfficeClawMcpTool` / `list_request_mcp_server_tools` / `validate_office_claw_mcp_config` / `bind_active_office_claw_mcp_tools` / `ensure_request_scoped_mcp_tool_allowed` / `preflight_mcp_server_reachable` | N1–N4 |
| `mcp_config.py` | `RequestScopedOfficeClawMcpTool.server_name` | 只读返回原 `_server_name`;供来源匹配使用,不改变 worker key、请求绑定或工具权限 |
+| `mcp_config.py` | `annotate_connector_catalog_result` / `set_unavailable_connectors`(请求级 MCP 工具实例) / `CONNECTOR_DISCOVERY_FAILED` / `CONNECTOR_NO_TOOLS` | N11;只改写两个目录工具的结果,无不可用连接器时原样返回 |
| `mcp_server_registry.py` | `McpServerRegistry` / `GlobalMcpWorkerPool` / `get_mcp_server_registry` / `start_mcp_registry_runtime` / `snapshot_for_chat` / `acquire_worker` / `redact_mcp_config` / `extract_mcp_server_list` / `McpRegistrySettings` | N5 / N6 |
| `mcp_server_registry.py` | `snapshot_for_deepresearch(name) -> tuple[dict, list, dict]` | N10;缺失抛 `UnknownMcpServerError`,停用抛 `DisabledMcpServerError` |
| `mcp_call_timeout_patch.py` | `apply_mcp_call_timeout_patch` / `force_invalidate_mcp_client` / `is_retryable_mcp_dead_session_error` / `DEFAULT_CALL_TIMEOUT = 30.0` | N7 |
@@ -133,6 +142,7 @@ mcp_tool_list_refresh_patch.py ┘ 唯一装配点:interface_deep.DeepAdapter.
| list 接口回显配置 | 凭据脱敏 | `redact_mcp_config` 测试 |
| 研究期间来源停用、删除或变更 | 专用端点拒绝继续委派 | `test_deepresearch_mcp_review_regressions.py` |
| 研究恢复时新增连接或更换来源 | 不扩张首次来源集合 | 同上及 `test_deepresearch_mcp_search.py` |
+| 请求级连接器发现失败 / 零工具,而宿主连接器目录仍显示已连接 | 目录工具结果追加本轮不可用说明(N11) | `test_failed_connector_discovery_is_reported_on_catalog_lookup` 等 |
## 修改检查单
diff --git a/jiuwenswarm/common/mcp_config.py b/jiuwenswarm/common/mcp_config.py
index 96786f0037..948ee99212 100644
--- a/jiuwenswarm/common/mcp_config.py
+++ b/jiuwenswarm/common/mcp_config.py
@@ -2516,6 +2516,47 @@ async def list_office_claw_mcp_tools(
return copy.deepcopy(tools)
+_LIST_CONNECTORS_TOOL = "office_claw_list_connectors"
+_GET_CONNECTOR_TOOLS_TOOL = "office_claw_get_connector_tools"
+_CONNECTOR_CATALOG_TOOL_NAMES = frozenset({_LIST_CONNECTORS_TOOL, _GET_CONNECTOR_TOOLS_TOOL})
+CONNECTOR_DISCOVERY_FAILED = "工具发现失败(连接器进程未能启动或连接被关闭)"
+CONNECTOR_NO_TOOLS = "未提供任何可用工具(工具可能已全部停用)"
+
+
+def annotate_connector_catalog_result(
+ tool_name: str,
+ arguments: Mapping[str, Any],
+ text: str | None,
+ unavailable: Mapping[str, str],
+ *,
+ is_error: bool = False,
+) -> str | None:
+ if tool_name not in _CONNECTOR_CATALOG_TOOL_NAMES or not unavailable:
+ return text
+ queried = ""
+ if tool_name == _GET_CONNECTOR_TOOLS_TOOL:
+ queried = str(arguments.get("connectorName") or "").strip().casefold()
+ # 查询参数名由宿主 MCP 服务定义;取不到查询名时按列出连接器全量标注,避免参数名变化后静默失效
+ if queried:
+ hits = {name: reason for name, reason in unavailable.items() if name.casefold() == queried}
+ else:
+ hits = dict(unavailable)
+ if not hits:
+ return text
+ lines = "\n".join(f"- {name}:{reason}" for name, reason in sorted(hits.items()))
+ # 宿主返回的错误文本原样保留,但不能称作"目录记录"
+ preface = "以上为连接器目录记录,不代表本轮可调用。" if text and not is_error else ""
+ note = (
+ f"[本次请求的连接器实际加载结果] {preface}"
+ "以下连接器本次请求没有加载任何工具,目录中列出的它们的工具在本轮均不可调用:\n"
+ f"{lines}\n"
+ f"不要再重复调用 {_LIST_CONNECTORS_TOOL} / {_GET_CONNECTOR_TOOLS_TOOL} 重试;"
+ "请直接告知用户该连接器当前不可用(可稍后重试,或在连接器页面重新连接、检查网络与代理),"
+ "并继续完成不依赖它的部分。"
+ )
+ return f"{text}\n\n{note}" if text else note
+
+
class RequestScopedOfficeClawMcpTool(Tool):
"""Invoke one OfficeClaw tool through a long-lived request-scoped process.
@@ -2546,12 +2587,16 @@ class RequestScopedOfficeClawMcpTool(Tool):
self._request_id = str(request_id or "")
self._server_name = str(server_name or "")
self._use_global_pool = bool(use_global_pool)
+ self._unavailable_connectors: dict[str, str] = {}
@property
def server_name(self) -> str:
"""只读暴露工具所属来源,不改变请求级连接身份。"""
return self._server_name
+ def set_unavailable_connectors(self, unavailable: Mapping[str, str]) -> None:
+ self._unavailable_connectors = dict(unavailable)
+
async def _acquire_mcp_session(self, *, force_rebuild: bool = False):
if self._use_global_pool:
from jiuwenswarm.common.mcp_server_registry import get_mcp_server_registry
@@ -2635,7 +2680,11 @@ class RequestScopedOfficeClawMcpTool(Tool):
# 池化进程可能在请求中途死掉(崩溃/stdin 关闭):丢弃重建一次再重试。
session = await self._acquire_mcp_session(force_rebuild=True)
result = await session.call_tool(self._card.name, arguments=arguments)
- return {"result": _extract_mcp_result_text(result)}
+ text = annotate_connector_catalog_result(
+ self._card.name, arguments, _extract_mcp_result_text(result),
+ self._unavailable_connectors, is_error=getattr(result, "isError", False) is True,
+ )
+ return {"result": text}
except Exception as exc:
raise build_error(
StatusCode.TOOL_MCP_EXECUTION_ERROR,
@@ -2647,6 +2696,8 @@ class RequestScopedOfficeClawMcpTool(Tool):
__all__ = [
+ "CONNECTOR_DISCOVERY_FAILED",
+ "CONNECTOR_NO_TOOLS",
"OFFICE_CLAW_EXPECTED_TOOL_IDS_KWARG",
"OFFICE_CLAW_REQUEST_TOOL_ID_PREFIX",
"MCP_REGISTRY_REQUEST_TOOL_ID_PREFIX",
@@ -2654,6 +2705,7 @@ __all__ = [
"OfficeClawMcpRegistration",
"RequestScopedOfficeClawMcpTool",
"acquire_request_scoped_mcp_session",
+ "annotate_connector_catalog_result",
"bind_active_office_claw_mcp_tools",
"bind_office_claw_from_agent",
"clear_agent_office_claw_tool_ids",
diff --git a/jiuwenswarm/server/runtime/agent_adapter/interface_deep.py b/jiuwenswarm/server/runtime/agent_adapter/interface_deep.py
index 0634d88a51..9317636533 100644
--- a/jiuwenswarm/server/runtime/agent_adapter/interface_deep.py
+++ b/jiuwenswarm/server/runtime/agent_adapter/interface_deep.py
@@ -586,6 +586,8 @@ from jiuwenswarm.common.config import (
resolve_string_or_list_config,
)
from jiuwenswarm.common.mcp_config import (
+ CONNECTOR_DISCOVERY_FAILED,
+ CONNECTOR_NO_TOOLS,
MCP_REGISTRY_REQUEST_TOOL_ID_PREFIX,
OfficeClawMcpRegistration,
RequestScopedOfficeClawMcpTool,
@@ -2547,6 +2549,7 @@ class _RequestMcpToolBuffers:
pending_tools: list[tuple[RequestScopedOfficeClawMcpTool, bool]] = field(default_factory=list)
research_servers: list[dict[str, Any]] = field(default_factory=list, repr=False)
research_tool_names: dict[str, list[str]] = field(default_factory=dict)
+ unavailable_connectors: dict[str, str] = field(default_factory=dict)
_SESSION_ADAPTER_IDLE_TTL_ENV = "JIUWENSWARM_SESSION_ADAPTER_IDLE_TTL_SEC"
@@ -5165,7 +5168,15 @@ class JiuWenSwarmDeepAdapter:
"[JiuWenSwarmDeepAdapter] request-scoped MCP connector discovery failed: "
"request_id=%s server=%s error=%s", request.request_id, server_name, exc,
)
+ if server_name != "office-claw":
+ buffers.unavailable_connectors[server_name] = CONNECTOR_DISCOVERY_FAILED
continue
+ # Discovery reports failure as empty params; a legitimately empty
+ # connector (e.g. every tool filtered off) still returns params.
+ if server_name != "office-claw" and not tool_defs:
+ buffers.unavailable_connectors[server_name] = (
+ CONNECTOR_NO_TOOLS if params else CONNECTOR_DISCOVERY_FAILED
+ )
self._stage_request_mcp_tools(request, server_name, tool_defs, params, buffers)
if tool_defs:
from jiuwenswarm.agents.harness.common.tools.deepresearch.mcp_search import project_search_server
@@ -5313,6 +5324,15 @@ class JiuWenSwarmDeepAdapter:
request, office_claw_config, buffers, yield_to_existing=True,
)
+ if buffers.unavailable_connectors:
+ logger.warning(
+ "[JiuWenSwarmDeepAdapter] request-scoped MCP connectors unavailable this request: "
+ "request_id=%s connectors=%s", request.request_id, buffers.unavailable_connectors,
+ )
+ for tool, _strict in buffers.pending_tools:
+ if tool.server_name == "office-claw":
+ tool.set_unavailable_connectors(buffers.unavailable_connectors)
+
if not replace_request_scoped_mcp_registration(generation, generation):
logger.info("[latency] stage=2 name=mcp request_id=%s", request.request_id)
return generation
diff --git a/tests/unit_tests/agentserver/test_request_scoped_office_claw_mcp.py b/tests/unit_tests/agentserver/test_request_scoped_office_claw_mcp.py
index e2fb66cad9..95431d62d9 100644
--- a/tests/unit_tests/agentserver/test_request_scoped_office_claw_mcp.py
+++ b/tests/unit_tests/agentserver/test_request_scoped_office_claw_mcp.py
@@ -1856,3 +1856,159 @@ def test_custom_data_block_without_mime_type_is_summarized() -> None:
summary = _mcp_non_text_summary(SimpleNamespace(data="C" * 10_000))
assert summary == "[binary content: unknown, 10000 base64 chars]"
+
+
+def _catalog_tool_list() -> list[dict[str, object]]:
+ return [
+ {"name": "office_claw_list_connectors", "description": "list", "input_params": {"type": "object"}},
+ {"name": "office_claw_get_connector_tools", "description": "tools", "input_params": {"type": "object"}},
+ ]
+
+
+async def _invoke_catalog_tool(
+ registration: OfficeClawMcpRegistration, tool_name: str, arguments: dict[str, object], catalog_text: str,
+ *, is_error: bool = False,
+) -> str:
+ from mcp.types import CallToolResult, TextContent
+
+ tool = next(item for item in registration.tool_instances if item.card.name == tool_name)
+ result = CallToolResult(content=[TextContent(type="text", text=catalog_text)], isError=is_error)
+ session = SimpleNamespace(call_tool=AsyncMock(return_value=result))
+ with (
+ patch.object(tool, "_acquire_mcp_session", new=AsyncMock(return_value=session)),
+ patch("jiuwenswarm.common.mcp_config.ensure_request_scoped_mcp_tool_allowed"),
+ patch("jiuwenswarm.common.mcp_config.ensure_office_claw_tool_invocation_matches_active"),
+ ):
+ result = await tool._invoke_with_active_binding(arguments)
+ return result["result"]
+
+
+async def _register_with_connector_discovery(
+ monkeypatch: pytest.MonkeyPatch, discovery: dict[str, tuple[list[dict[str, object]], dict[str, object]]],
+) -> tuple[JiuWenSwarmDeepAdapter, OfficeClawMcpRegistration]:
+ for key, value in _startup_env().items():
+ monkeypatch.setenv(key, value)
+ monkeypatch.setattr(interface_deep.Runner, "resource_mgr", _ResourceManager())
+ monkeypatch.setattr(interface_deep, "list_office_claw_mcp_tools", AsyncMock(return_value=_catalog_tool_list()))
+
+ async def _fake_discovery(server_name, config):
+ return discovery[server_name]
+
+ monkeypatch.setattr(interface_deep, "list_request_mcp_server_tools", AsyncMock(side_effect=_fake_discovery))
+ adapter = _bare_session_adapter()
+ registration = await adapter.register_request_scoped_office_claw_mcp(
+ _request_with_connectors(_valid_config(), connectors={name: {"command": "npx"} for name in discovery})
+ )
+ return adapter, registration
+
+
+async def test_failed_connector_discovery_is_reported_on_catalog_lookup(monkeypatch: pytest.MonkeyPatch) -> None:
+ from jiuwenswarm.common.mcp_config import CONNECTOR_DISCOVERY_FAILED
+
+ adapter, registration = await _register_with_connector_discovery(
+ monkeypatch,
+ {
+ "huaweicloud-devkit": ([], {}),
+ "filesystem": ([{"name": "list_dir", "description": "", "input_params": {}}], {"command": "node"}),
+ },
+ )
+ catalog_text = '{"connector":{"name":"huaweicloud-devkit","status":"connected","enabled":true},"tools":[]}'
+ try:
+ assert "list_dir" in registration.tool_names
+ text = await _invoke_catalog_tool(
+ registration, "office_claw_get_connector_tools", {"connectorName": "huaweicloud-devkit"}, catalog_text,
+ )
+ assert text.startswith(catalog_text)
+ assert f"- huaweicloud-devkit:{CONNECTOR_DISCOVERY_FAILED}" in text
+ assert "不要再重复调用" in text
+
+ other = await _invoke_catalog_tool(
+ registration, "office_claw_get_connector_tools", {"connectorName": "filesystem"}, catalog_text,
+ )
+ assert other == catalog_text
+
+ listed = await _invoke_catalog_tool(registration, "office_claw_list_connectors", {}, catalog_text)
+ assert "huaweicloud-devkit" in listed.removeprefix(catalog_text)
+ assert "filesystem:" not in listed
+ finally:
+ await adapter.cleanup_request_scoped_office_claw_mcp(registration)
+
+
+async def test_host_error_text_is_kept_but_not_called_catalog_record(monkeypatch: pytest.MonkeyPatch) -> None:
+ adapter, registration = await _register_with_connector_discovery(monkeypatch, {"huaweicloud-devkit": ([], {})})
+ error_text = "Callback failed (409): Connector is not connected: huaweicloud-devkit"
+ try:
+ for arguments in ({"connectorName": "huaweicloud-devkit"}, {}):
+ text = await _invoke_catalog_tool(
+ registration, "office_claw_get_connector_tools", arguments, error_text, is_error=True,
+ )
+ assert text.startswith(error_text)
+ assert "- huaweicloud-devkit:" in text
+ assert "以上为连接器目录记录" not in text
+ ok = await _invoke_catalog_tool(registration, "office_claw_list_connectors", {}, "{}")
+ assert "以上为连接器目录记录" in ok
+ finally:
+ await adapter.cleanup_request_scoped_office_claw_mcp(registration)
+
+
+async def test_connector_without_tools_is_reported_separately(monkeypatch: pytest.MonkeyPatch) -> None:
+ from jiuwenswarm.common.mcp_config import CONNECTOR_NO_TOOLS
+
+ adapter, registration = await _register_with_connector_discovery(
+ monkeypatch, {"huaweicloud-devkit": ([], {"_mcp_client_type": "stdio"})},
+ )
+ try:
+ text = await _invoke_catalog_tool(registration, "office_claw_list_connectors", {}, "{}")
+ assert f"- huaweicloud-devkit:{CONNECTOR_NO_TOOLS}" in text
+ finally:
+ await adapter.cleanup_request_scoped_office_claw_mcp(registration)
+
+
+async def test_healthy_connectors_leave_catalog_result_untouched(monkeypatch: pytest.MonkeyPatch) -> None:
+ adapter, registration = await _register_with_connector_discovery(
+ monkeypatch, {"filesystem": ([{"name": "list_dir", "description": "", "input_params": {}}], {"command": "node"})},
+ )
+ try:
+ text = await _invoke_catalog_tool(registration, "office_claw_list_connectors", {}, '{"total":1}')
+ assert text == '{"total":1}'
+ finally:
+ await adapter.cleanup_request_scoped_office_claw_mcp(registration)
+
+
+def test_annotation_only_applies_to_catalog_tools() -> None:
+ from jiuwenswarm.common.mcp_config import annotate_connector_catalog_result
+
+ unavailable = {"huaweicloud-devkit": "工具发现失败"}
+ assert annotate_connector_catalog_result("office_claw_post_message", {}, "ok", unavailable) == "ok"
+ annotated = annotate_connector_catalog_result(
+ "office_claw_get_connector_tools", {"connectorName": "HuaweiCloud-DevKit"}, None, unavailable,
+ )
+ assert annotated is not None and annotated.startswith("[本次请求的连接器实际加载结果]")
+
+
+def test_get_connector_tools_without_name_falls_back_to_full_annotation() -> None:
+ from jiuwenswarm.common.mcp_config import annotate_connector_catalog_result
+
+ unavailable = {"huaweicloud-devkit": "工具发现失败", "flaky-demo": "工具发现失败"}
+ for arguments in ({}, {"connectorName": " "}, {"name": "huaweicloud-devkit"}):
+ text = annotate_connector_catalog_result("office_claw_get_connector_tools", arguments, "err", unavailable)
+ assert "- huaweicloud-devkit:" in text and "- flaky-demo:" in text
+ other = annotate_connector_catalog_result(
+ "office_claw_get_connector_tools", {"connectorName": "filesystem"}, "ok", unavailable,
+ )
+ assert other == "ok"
+
+
+def test_empty_catalog_text_has_no_dangling_preface() -> None:
+ from jiuwenswarm.common.mcp_config import annotate_connector_catalog_result
+
+ unavailable = {"huaweicloud-devkit": "工具发现失败"}
+ with_text = annotate_connector_catalog_result("office_claw_list_connectors", {}, "{}", unavailable)
+ assert "以上为连接器目录记录" in with_text
+ for empty in (None, ""):
+ note = annotate_connector_catalog_result("office_claw_list_connectors", {}, empty, unavailable)
+ assert "以上" not in note and "- huaweicloud-devkit:" in note