fix(toolset): 工具传递改为展开的 tools 列表，不再用 FunctionToolset 包装

前端/DB 仍用 toolset 做逻辑分组管理，但传给 pydantic-ai Agent 时
把 toolset 内的 callable 展开为 tools=[] 扁平列表，MCP server 等
需要 toolset 语义的单独走 toolsets=[] 参数。解决工具"存在但调不了"的问题。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

kilostar/api/agent.py

@@ -23,7 +23,7 @@ from fastapi import HTTPException
 from typing import Optional, List, Dict
 from kilostar.utils.check_user.role_check import RoleChecker
 from kilostar.core.postgres_database.model import UserAuthority
-from kilostar.utils.mcp_helper import get_all_toolsets_for_scope
+from kilostar.utils.mcp_helper import get_all_tools_and_toolsets_for_scope
 from kilostar.utils.i18n import t
 
 agent_router = APIRouter(prefix="/api/v1/agent", tags=["agent"])
@@ -84,7 +84,7 @@ async def load_agent(
             )
 
             scope = agent_register.individual_name
-            toolsets = await get_all_toolsets_for_scope(
+            tools, toolsets = await get_all_tools_and_toolsets_for_scope(
                 scope, toolset_ids=agent_register.toolsets
             )
 
@@ -102,6 +102,7 @@ async def load_agent(
                         global_state_machine,
                         agent_register.provider_title,
                         agent_register.model_id,
+                        tools,
                         toolsets,
                         accept_lang,
                         persona_prompt,
@@ -112,6 +113,7 @@ async def load_agent(
                         global_state_machine,
                         agent_register.provider_title,
                         agent_register.model_id,
+                        tools,
                         toolsets,
                         accept_lang,
                         persona_prompt,

kilostar/core/global_state_machine/gsm_snapshot.py

@@ -142,31 +142,24 @@ def reset_local_cache() -> None:
 # ─── 客户端 helper：从快照重建本地视图 ─────────────────────────────
 
 
-def build_toolsets_for_scope(
+def build_tools_for_scope(
     snapshot: GSMSnapshot,
     scope: str,
     toolset_ids: Optional[List[str]] = None,
-) -> List[Any]:
+) -> List[Callable]:
-    """在调用方进程里按 ``snapshot`` 现场组装 FunctionToolset 列表。
+    """从快照中按 toolset 配置展开为扁平的 tool callable 列表。
 
-    新模型下"系统工具集"也存在 ``custom_toolsets`` 里（``is_system=True``），
+    管理层面仍然用 toolset 做逻辑分组（前端展示、权限控制），
-    所以本函数只按 ``toolset_ids`` 在 ``custom_toolsets`` 中按需挑选并装配；
+    但传给 pydantic-ai Agent 时直接展开为 tools 列表，避免
-    所有工具函数（system + 第三方）都从 ``snapshot.all_funcs`` 统一查表。
+    FunctionToolset 封装带来的兼容性问题。
 
     Args:
         snapshot: 当前 GSM 快照。
-        scope: 调用方所属 scope（保留参数：未来可按 scope 过滤系统 toolset
+        scope: 调用方所属 scope（保留参数，未来可按 scope 过滤可见性）。
-               的可见性，目前仅用于命名/日志）。
+        toolset_ids: agent 配置的 toolset 列表；为 None 表示返回全部。
-        toolset_ids: agent 配置的 toolset 列表；为 None 表示返回全部 toolset
-                     （兼容老调用，但建议传入显式列表）。
     """
-    try:
+    result: List[Callable] = []
-        from pydantic_ai.toolsets import FunctionToolset
+    seen: set = set()
-    except ImportError:
-        _logger.warning("pydantic_ai.toolsets unavailable; cannot build toolsets")
-        return []
-
-    result: List[Any] = []
     target_ids = (
         list(toolset_ids)
         if toolset_ids is not None
@@ -177,14 +170,12 @@ def build_toolsets_for_scope(
         if not defn:
             continue
         names = defn.get("tools") or []
-        funcs = [snapshot.all_funcs[n] for n in names if n in snapshot.all_funcs]
+        for name in names:
-        if not funcs:
+            if name in seen:
-            continue
+                continue
-        try:
+            func = snapshot.all_funcs.get(name)
-            result.append(
+            if func is not None:
-                FunctionToolset(tools=funcs, id=f"toolset::{toolset_id}")
+                result.append(func)
-            )
+                seen.add(name)
-        except Exception as e:  # pragma: no cover - 防御
-            _logger.error(f"build toolset {toolset_id} failed: {e}")
 
     return result

kilostar/core/individual/consciousness_node/consciousness_node.py

@@ -45,6 +45,7 @@ class ConsciousnessNode:
         global_state_machine: GlobalStateMachine,
         provider_title: str,
         model_id: str,
+        tools=None,
         toolsets=None,
         locale: str | None = None,
         custom_system_prompt: str | None = None,
@@ -67,6 +68,7 @@ class ConsciousnessNode:
             system_prompt=system_prompt,
             deps_type=ConsciousnessNodeDeps,
             agent_name="consciousness_node",
+            tools=tools,
             toolsets=toolsets,
         )
 

kilostar/core/individual/regulatory_node/regulatory_node.py

@@ -47,6 +47,7 @@ class RegulatoryNode:
         global_state_machine: GlobalStateMachine,
         provider_title: str,
         model_id: str,
+        tools=None,
         toolsets=None,
         locale: str | None = None,
         custom_system_prompt: str | None = None,
@@ -59,7 +60,8 @@ class RegulatoryNode:
             global_state_machine: 全局状态机
             provider_title: 供应商名
             model_id: 模型id
-            toolsets: 已装配好的 FunctionToolset 列表
+            tools: 展开的 tool callable 列表
+            toolsets: MCP 等外部 toolset 列表
             locale: 语言代码（zh/en），控制system prompt语言
             custom_system_prompt: 管理员自定义追加提示词（可选）
         Returns:
@@ -84,6 +86,7 @@ class RegulatoryNode:
             system_prompt=system_prompt,
             deps_type=RegulatoryNodeDeps,
             agent_name="regulatory_node",
+            tools=tools,
             toolsets=toolsets,
         )
 

kilostar/utils/mcp_helper.py

@@ -100,34 +100,42 @@ async def get_mcp_toolsets_from_gsm() -> List[Any]:
         return []
 
 
-async def get_all_toolsets_for_scope(
+async def get_all_tools_and_toolsets_for_scope(
     scope: str, toolset_ids: Optional[List[str]] = None
-) -> List[Any]:
+) -> tuple:
-    """汇总某个 scope 下的全部 toolset：system + personal + mcp。
+    """汇总某个 scope 下的工具：展开的 tool callable 列表 + MCP toolsets。
 
     Args:
         scope: 调用方所属 scope。
         toolset_ids: agent 配置的 toolset 列表；为 None 或空列表表示返回全部。
 
-    返回顺序保持稳定：先本地 toolset（按 toolset_ids），再 MCP toolset。
+    Returns:
-    任意一类拉取失败仅记录日志，不影响其他类。
+        (tools, toolsets) — tools 是展开的 callable 列表（传给 Agent(tools=...)），
+        toolsets 是 MCP server 等需要 toolset 语义的对象（传给 Agent(toolsets=...)）。
     """
+    tools: List[Any] = []
     toolsets: List[Any] = []
     try:
         from kilostar.core.global_state_machine.gsm_snapshot import (
-            build_toolsets_for_scope,
+            build_tools_for_scope,
             fetch_snapshot,
         )
 
         snapshot = await fetch_snapshot()
         effective_ids = toolset_ids if toolset_ids else None
-        local = build_toolsets_for_scope(snapshot, scope, toolset_ids=effective_ids)
+        tools = build_tools_for_scope(snapshot, scope, toolset_ids=effective_ids)
-        if local:
-            toolsets.extend(local)
     except Exception as e:
-        logger.error(f"Failed to load local toolsets from GSM ({scope}): {e}")
+        logger.error(f"Failed to load tools from GSM ({scope}): {e}")
 
-    toolsets.extend(await get_mcp_toolsets_from_gsm())
+    toolsets = await get_mcp_toolsets_from_gsm()
+    return tools, toolsets
+
+
+async def get_all_toolsets_for_scope(
+    scope: str, toolset_ids: Optional[List[str]] = None
+) -> List[Any]:
+    """兼容旧调用：返回 MCP toolsets 列表（不再包含 FunctionToolset）。"""
+    _, toolsets = await get_all_tools_and_toolsets_for_scope(scope, toolset_ids)
     return toolsets
 
 

kilostar/worker_individual/base_individual.py

@@ -64,7 +64,7 @@ class BaseIndividual:
             system_prompt: 该 Agent 的基础系统提示词，会和 task_event 拼接成动态提示词。
             toolsets: 显式传入的外部工具集；为 ``None`` 时会自动按配置拉取。
         """
-        from kilostar.utils.mcp_helper import get_all_toolsets_for_scope
+        from kilostar.utils.mcp_helper import get_all_tools_and_toolsets_for_scope
         from kilostar.core.global_state_machine.gsm_snapshot import fetch_snapshot
 
         global_state_machine = ray_actor_hook(
@@ -84,9 +84,11 @@ class BaseIndividual:
         agent_factory = AgentFactory()
 
         if toolsets is None:
-            toolsets = await get_all_toolsets_for_scope(
+            tools, toolsets = await get_all_tools_and_toolsets_for_scope(
                 agent_name, toolset_ids=toolset_ids
             )
+        else:
+            tools = []
 
         self.agent = agent_factory.create_agent(
             provider=provider,
@@ -95,6 +97,7 @@ class BaseIndividual:
             system_prompt=system_prompt,
             deps_type=WorkerIndividualDeps,
             agent_name=agent_name,
+            tools=tools,
             toolsets=toolsets,
         )
 

tests/unit/test_gsm_snapshot.py

@@ -308,13 +308,13 @@ async def test_fetch_snapshot_use_cache_false_skips_cache(monkeypatch):
     assert result is fresh
 
 
-# ─── build_toolsets_for_scope 客户端 helper ────────────────────────
+# ─── build_tools_for_scope 客户端 helper ────────────────────────
 
 
-def test_build_toolsets_for_scope_assembles_system_and_custom():
+def test_build_tools_for_scope_assembles_system_and_custom():
-    """客户端按 snapshot 的 custom_toolsets + all_funcs 现场组装。"""
+    """客户端按 snapshot 的 custom_toolsets + all_funcs 展开为扁平 callable 列表。"""
     from kilostar.core.global_state_machine.gsm_snapshot import (
-        build_toolsets_for_scope,
+        build_tools_for_scope,
     )
 
     def _sys_default():
@@ -334,20 +334,19 @@ def test_build_toolsets_for_scope_assembles_system_and_custom():
         },
     )
 
-    result = build_toolsets_for_scope(snap, "control_node")
+    result = build_tools_for_scope(snap, "control_node")
-    assert len(result) == 2
+    assert len(result) == 3
-    ids = [getattr(t, "id", None) for t in result]
+    assert result == [_sys_default, _sys_scope, _tp_a]
-    assert ids == ["toolset::system_basic", "toolset::grp"]
 
 
-def test_build_toolsets_for_scope_skips_empty_buckets():
+def test_build_tools_for_scope_skips_empty_buckets():
-    """没有工具的 scope 不应产出 toolset，避免空 FunctionToolset 噪声。"""
+    """没有工具的 scope 返回空列表。"""
     from kilostar.core.global_state_machine.gsm_snapshot import (
-        build_toolsets_for_scope,
+        build_tools_for_scope,
     )
 
     snap = GSMSnapshot(
         all_funcs={},
         custom_toolsets={},
     )
-    assert build_toolsets_for_scope(snap, "control_node") == []
+    assert build_tools_for_scope(snap, "control_node") == []

tests/unit/test_utils_mcp_helper.py

@@ -104,11 +104,11 @@ async def test_get_mcp_toolsets_from_gsm_uses_configs_via_snapshot(monkeypatch):
     assert getattr(toolsets[0], "id", None) == "fs"
 
 
-# ─── get_all_toolsets_for_scope ──────────────────────────────────────────────
+# ─── get_all_tools_and_toolsets_for_scope ──────────────────────────────────────────────
 
 
-async def test_get_all_toolsets_for_scope_merges_local_and_mcp(monkeypatch):
+async def test_get_all_tools_and_toolsets_for_scope_merges_local_and_mcp(monkeypatch):
-    """本地 toolset 列表和 mcp toolset 列表都应该被拼接。"""
+    """本地 tools 列表和 mcp toolsets 列表都应该被正确返回。"""
 
     monkeypatch.setattr(mcp_helper, "_MCP_AVAILABLE", True)
 
@@ -126,25 +126,25 @@ async def test_get_all_toolsets_for_scope_merges_local_and_mcp(monkeypatch):
     monkeypatch.setattr(snap_mod, "fetch_snapshot", _fake_fetch)
     monkeypatch.setattr(
         snap_mod,
-        "build_toolsets_for_scope",
+        "build_tools_for_scope",
         lambda s, scope, **kw: [local_a, local_b],
     )
 
-    result = await mcp_helper.get_all_toolsets_for_scope("control_node")
+    tools, toolsets = await mcp_helper.get_all_tools_and_toolsets_for_scope("control_node")
-    assert result == [local_a, local_b]
+    assert tools == [local_a, local_b]
+    assert toolsets == []
 
 
-async def test_get_all_toolsets_for_scope_local_failure_does_not_block_mcp(
+async def test_get_all_tools_and_toolsets_local_failure_does_not_block_mcp(
     monkeypatch,
 ):
-    """本地 toolset 拉取失败时仍然要返回 mcp toolset。"""
+    """本地 tools 拉取失败时仍然要返回 mcp toolsets。"""
 
     monkeypatch.setattr(mcp_helper, "_MCP_AVAILABLE", True)
 
     from kilostar.core.global_state_machine import gsm_snapshot as snap_mod
     from kilostar.core.global_state_machine.gsm_snapshot import GSMSnapshot
 
-    # local 路径：fetch 成功但 build_toolsets_for_scope 抛错
     snap = GSMSnapshot(
         version=1,
         mcp_servers={
@@ -164,11 +164,12 @@ async def test_get_all_toolsets_for_scope_local_failure_does_not_block_mcp(
         raise RuntimeError("boom")
 
     monkeypatch.setattr(snap_mod, "fetch_snapshot", _fake_fetch)
-    monkeypatch.setattr(snap_mod, "build_toolsets_for_scope", _broken_build)
+    monkeypatch.setattr(snap_mod, "build_tools_for_scope", _broken_build)
 
-    result = await mcp_helper.get_all_toolsets_for_scope("control_node")
+    tools, toolsets = await mcp_helper.get_all_tools_and_toolsets_for_scope("control_node")
-    assert len(result) == 1
+    assert tools == []
-    assert getattr(result[0], "id", None) == "fs"
+    assert len(toolsets) == 1
+    assert getattr(toolsets[0], "id", None) == "fs"
 
 
 # ─── list_mcp_tools_for_configs ──────────────────────────────────────────────