fix: 修复SkillToolSet中tool_filter失效的问题(#352)

docs/mkdocs/en/skill.md

@@ -183,6 +183,74 @@ Key points:
   - Package entry (aggregated exports): [trpc_agent_sdk/skills/tools/__init__.py](../../../trpc_agent_sdk/skills/tools/__init__.py)
   - `skill_run` implementation: [trpc_agent_sdk/skills/tools/_skill_run.py](../../../trpc_agent_sdk/skills/tools/_skill_run.py) (for other tools, see **Declaration location** in each section below)
 
+#### Restricting Skill Tools by Use Case
+
+`SkillToolSet` exposes all built-in tools by default. You normally do not need
+to configure a filter. To reduce the tools visible to the LLM, enforce access
+control, or enable only a particular type of skill, configure `tool_filter`
+together with `is_include_all_tools=False`:
+
+```python
+# Instruction-only skill: load SKILL.md and docs without running its scripts.
+skill_tool_set = SkillToolSet(
+    repository=repository,
+    tool_filter=["skill_load"],
+    is_include_all_tools=False,
+)
+
+# Script-based skill: load its instructions, then run a one-shot command.
+skill_tool_set = SkillToolSet(
+    repository=repository,
+    tool_filter=["skill_load", "skill_run"],
+    is_include_all_tools=False,
+    run_tool_kwargs={"require_skill_loaded": True},
+)
+
+# You can also make the decision dynamically for each invocation.
+def select_skill_tool(tool, invocation_context):
+    allowed_tools = invocation_context.session_state.get(
+        "allowed_skill_tools", []
+    )
+    return tool.name in allowed_tools
+
+skill_tool_set = SkillToolSet(
+    repository=repository,
+    tool_filter=select_skill_tool,
+    is_include_all_tools=False,
+)
+```
+
+`tool_filter` accepts either a list of tool names or a predicate function. The
+predicate is evaluated by `get_tools()` against the current
+`InvocationContext` on every invocation, so it can expose tools based on user
+permissions, session state, or tenant configuration. The default
+`is_include_all_tools=True` ignores the filter for backward compatibility; the
+filter takes effect only when this option is set to `False`.
+
+The tools serve the following purposes:
+
+- `skill_load`: Loads the skill body and documentation. An instruction-only
+  skill that provides guidance, prompts, or domain knowledge usually needs only
+  this tool.
+- `skill_run`: Runs a one-shot script or command from a skill. It can run
+  directly by default. If `run_tool_kwargs={"require_skill_loaded": True}` is
+  set, `skill_load` must also be allowed.
+- `skill_exec`: Starts an interactive or long-running skill command.
+- `skill_list`, `skill_list_docs`, and `skill_select_docs`: Optional helpers
+  for skill discovery and on-demand documentation selection.
+- `workspace_exec`, `workspace_write_stdin`, and `workspace_kill_session`:
+  Run, provide input to, or terminate workspace commands directly.
+- `workspace_save_artifact`: Saves workspace files as artifacts when needed.
+- `skill_list_tools` and `skill_select_tools`: Available only from
+  `SkillToolSetWithDynamicTools` for dynamic business-tool selection.
+
+The filter uses allowlist semantics and does not automatically add dependencies.
+For example, if only `skill_load` is allowed, the LLM cannot call `skill_run`.
+An instruction-only skill can keep only `skill_load`; a typical script-based
+skill should keep at least `skill_load` and `skill_run`. Add the corresponding
+tools when documentation selection, interactive execution, workspace
+operations, or artifacts are required.
+
 ### 3) Running the Example
 
 Full interactive demo: [examples/skills/run_agent.py](../../../examples/skills/run_agent.py)

docs/mkdocs/zh/skill.md

@@ -182,6 +182,68 @@ Always use environment variables in commands:
 - **代码位置**：
   - 工具包入口（聚合导出）：[trpc_agent_sdk/skills/tools/__init__.py](../../../trpc_agent_sdk/skills/tools/__init__.py)
   - `skill_run` 实现：[trpc_agent_sdk/skills/tools/_skill_run.py](../../../trpc_agent_sdk/skills/tools/_skill_run.py)（其余工具见下文各节「声明位置」）
+
+#### 按场景限制 Skill 工具
+
+`SkillToolSet` 默认暴露全部内置工具。通常不需要配置过滤器；如果需要减少
+LLM 可见工具、实施权限控制，或者只启用某类 Skill，可以同时配置
+`tool_filter` 和 `is_include_all_tools=False`：
+
+```python
+# 指导型 Skill：只加载 SKILL.md 和文档，不执行其中的脚本。
+skill_tool_set = SkillToolSet(
+    repository=repository,
+    tool_filter=["skill_load"],
+    is_include_all_tools=False,
+)
+
+# 脚本型 Skill：先加载说明，再执行一次性命令。
+skill_tool_set = SkillToolSet(
+    repository=repository,
+    tool_filter=["skill_load", "skill_run"],
+    is_include_all_tools=False,
+    run_tool_kwargs={"require_skill_loaded": True},
+)
+
+# 也可以根据当前调用上下文动态判断。
+def select_skill_tool(tool, invocation_context):
+    allowed_tools = invocation_context.session_state.get(
+        "allowed_skill_tools", []
+    )
+    return tool.name in allowed_tools
+
+skill_tool_set = SkillToolSet(
+    repository=repository,
+    tool_filter=select_skill_tool,
+    is_include_all_tools=False,
+)
+```
+
+`tool_filter` 支持工具名称列表或 Predicate 函数。Predicate 会在每次
+`get_tools()` 时使用当前 `InvocationContext` 重新判断，因此可以根据用户权限、
+会话状态或租户配置动态暴露工具。默认的 `is_include_all_tools=True` 会忽略过滤器，
+保持向后兼容；只有设置为 `False` 时过滤器才会生效。
+
+按用途可以将工具分为：
+
+- `skill_load`：加载 Skill 主体和文档。仅提供操作指导、Prompt 或领域知识的
+  Skill 通常只需要该工具。
+- `skill_run`：执行 Skill 中的一次性脚本或命令。默认允许直接运行；如果设置
+  `run_tool_kwargs={"require_skill_loaded": True}`，必须同时允许 `skill_load`。
+- `skill_exec`：启动需要交互或长时间运行的 Skill 命令。
+- `skill_list`、`skill_list_docs`、`skill_select_docs`：用于发现 Skill 和按需
+  选择文档，均为辅助工具。
+- `workspace_exec`、`workspace_write_stdin`、`workspace_kill_session`：直接执行、
+  输入或终止工作区命令。
+- `workspace_save_artifact`：需要将工作区文件保存为 Artifact 时使用。
+- `skill_list_tools`、`skill_select_tools`：仅由
+  `SkillToolSetWithDynamicTools` 提供，用于动态业务工具选择。
+
+过滤器采用白名单语义，不会自动补齐依赖。例如仅允许 `skill_load` 后，LLM
+不能再调用 `skill_run`。因此，指导型 Skill 可以只保留 `skill_load`；常规脚本型
+Skill 建议至少保留 `skill_load` 和 `skill_run`；需要文档选择、交互执行、工作区
+操作或 Artifact 时，再加入对应工具。
+
 ### 3) 运行示例
 
 完整示例交互式演示：[examples/skills/run_agent.py](../../../examples/skills/run_agent.py)

tests/skills/test_toolset.py

@@ -16,6 +16,8 @@
 
 from unittest.mock import MagicMock
 
+import pytest
+
 from trpc_agent_sdk.skills._dynamic_toolset import SkillToolSetWithDynamicTools
 from trpc_agent_sdk.skills._toolset import SkillToolSet
 
@@ -28,6 +30,7 @@ def _make_ctx():
 
 
 class TestSkillToolSetInit:
+
     def test_default_init(self, tmp_path):
         ts = SkillToolSet(paths=[str(tmp_path)])
         assert ts.name == "skill_toolset"
@@ -41,6 +44,7 @@ def test_custom_repository(self):
 
 
 class TestSkillToolSetGetTools:
+
     async def test_get_tools_returns_tools(self, tmp_path):
         ts = SkillToolSet(paths=[str(tmp_path)])
         ctx = _make_ctx()
@@ -74,7 +78,51 @@ async def test_get_tools_sets_metadata(self, tmp_path):
         ctx.agent_context.with_metadata.assert_called()
 
 
+@pytest.mark.parametrize("toolset_cls", [SkillToolSet, SkillToolSetWithDynamicTools])
+class TestSkillToolSetFiltering:
+
+    async def test_name_filter_applies_to_first_and_cached_calls(self, tmp_path, toolset_cls):
+        ts = toolset_cls(
+            paths=[str(tmp_path)],
+            tool_filter=["skill_load"],
+            is_include_all_tools=False,
+        )
+
+        for _ in range(2):
+            tools = await ts.get_tools(_make_ctx())
+            assert [tool.name for tool in tools] == ["skill_load"]
+
+    async def test_predicate_rechecks_current_context_without_filtering_cache(self, tmp_path, toolset_cls):
+
+        def predicate(tool, invocation_context):
+            return tool.name in invocation_context.allowed_tools
+
+        ts = toolset_cls(
+            paths=[str(tmp_path)],
+            tool_filter=predicate,
+            is_include_all_tools=False,
+        )
+
+        for allowed_tools in ({"skill_run"}, {"skill_load"}):
+            ctx = _make_ctx()
+            ctx.allowed_tools = allowed_tools
+            tools = await ts.get_tools(ctx)
+            assert {tool.name for tool in tools} == allowed_tools
+
+    async def test_include_all_tools_overrides_filter(self, tmp_path, toolset_cls):
+        ts = toolset_cls(
+            paths=[str(tmp_path)],
+            tool_filter=["skill_load"],
+            is_include_all_tools=True,
+        )
+
+        tools = await ts.get_tools(_make_ctx())
+        assert "skill_load" in {tool.name for tool in tools}
+        assert len(tools) > 1
+
+
 class TestSkillToolSetWithDynamicTools:
+
     async def test_get_tools_includes_dynamic_selection_helpers(self, tmp_path):
         ts = SkillToolSetWithDynamicTools(paths=[str(tmp_path)])
         ctx = _make_ctx()

trpc_agent_sdk/skills/_toolset.py

@@ -144,15 +144,21 @@ def repository(self) -> BaseSkillRepository:
         """Get the skill repository."""
         return self._repository
 
+    def _get_selected_tools(self, invocation_context: Optional[InvocationContext]) -> List[ToolABC]:
+        """Return tools selected for the current invocation."""
+        if not self._tool_filter or self._is_include_all_tools:
+            return self._default_tools
+        return [tool for tool in self._default_tools if self._is_tool_selected(tool, invocation_context)]
+
     @override
     async def get_tools(self, invocation_context: Optional[InvocationContext] = None) -> List[ToolABC]:
         """Get all tools from registered skills.
 
         Args:
-            invocation_context: Optional invocation context (not used currently)
+            invocation_context: Optional invocation context used for filtering.
 
         Returns:
-            List of tools from all registered skills
+            List of tools selected for the current invocation.
         """
         if self._repo_resolver is not None:
             repository = self._repo_resolver(invocation_context)
@@ -167,7 +173,7 @@ async def get_tools(self, invocation_context: Optional[InvocationContext] = None
             if not is_exist_skill_config(agent_context):
                 set_skill_config(agent_context, self._skill_config)
         if self._default_tools:
-            return self._default_tools.copy()
+            return self._get_selected_tools(invocation_context)
 
         tools: List[ToolABC] = []
         tools.append(self._load_tool)
@@ -184,4 +190,4 @@ async def get_tools(self, invocation_context: Optional[InvocationContext] = None
                 logger.warning("Failed to get tools from skill '%s': %s", skill_function.__name__, ex)
                 continue
         self._default_tools.extend(tools)
-        return tools
+        return self._get_selected_tools(invocation_context)