fix: 修复skill_exec未注入Skill专属环境变量的问题 (#359)

docs/mkdocs/en/skill.md

@@ -1016,6 +1016,12 @@ Assistant: Let me check what documentation is available.
 - Collects specified output files and returns them
 - Supports custom environment variable overrides
 
+Both `skill_run` and `skill_exec` call `repository.skill_run_env(skill_name)`
+to add skill-specific environment variables. Values returned by the hook do not
+override keys already present in the call's `env` or non-empty host environment
+values. Empty keys, blank values, and blocked keys such as `LD_PRELOAD` are ignored.
+If the hook raises an exception, command execution continues.
+
 **Prompt guidance**:
 
 This tool is called by the LLM when ready to execute actual commands. The prompt should include detailed usage guidelines:

docs/mkdocs/zh/skill.md

@@ -1009,6 +1009,11 @@ Assistant: Let me check what documentation is available.
 - 收集指定的输出文件并返回
 - 支持自定义环境变量覆盖
 
+`skill_run` 和 `skill_exec` 都会调用 `repository.skill_run_env(skill_name)`
+补充 Skill 专属环境变量。钩子返回的变量不会覆盖调用参数 `env` 中已有的键，也不会
+覆盖宿主环境中的非空值。空键、空白值以及禁止注入的键（如 `LD_PRELOAD`）会被忽略；
+钩子抛出异常时，命令仍继续执行。
+
 **提示词指导**：
 
 这个工具由 LLM 在准备好后执行实际命令。提示词应包含详细的使用指南：

tests/skills/tools/test_skill_exec.py

@@ -4,6 +4,7 @@
 #
 # tRPC-Agent-Python is licensed under Apache-2.0.
 
+import os
 from unittest.mock import AsyncMock
 from unittest.mock import MagicMock
 
@@ -13,10 +14,14 @@
 from trpc_agent_sdk.code_executors import DEFAULT_IO_YIELD_MS
 from trpc_agent_sdk.code_executors import DEFAULT_POLL_LINES
 from trpc_agent_sdk.code_executors import DEFAULT_SESSION_TTL_SEC
+from trpc_agent_sdk.code_executors import ENV_SKILL_NAME
+from trpc_agent_sdk.code_executors import WorkspaceRunResult
+from trpc_agent_sdk.skills.stager import SkillStageResult
 from trpc_agent_sdk.skills.tools._skill_exec import ExecInput
 from trpc_agent_sdk.skills.tools._skill_exec import PollSessionTool
 from trpc_agent_sdk.skills.tools._skill_exec import SkillExecTool
 from trpc_agent_sdk.skills.tools._skill_exec import WriteStdinTool
+from trpc_agent_sdk.skills.tools._skill_exec import _ExecSession
 from trpc_agent_sdk.skills.tools._skill_exec import _close_session
 from trpc_agent_sdk.skills.tools._skill_exec import _collect_final_result
 from trpc_agent_sdk.skills.tools._skill_exec import _detect_interaction
@@ -25,6 +30,7 @@
 from trpc_agent_sdk.skills.tools._skill_exec import _start_session
 from trpc_agent_sdk.skills.tools._skill_exec import create_exec_tools
 from trpc_agent_sdk.skills.tools._skill_run import SkillRunFile
+from trpc_agent_sdk.skills.tools._skill_run import SkillRunTool
 
 
 def _make_exec_tool() -> SkillExecTool:
@@ -40,6 +46,7 @@ def _make_exec_tool() -> SkillExecTool:
 
 
 class TestHelpers:
+
     def test_last_non_empty_line(self):
         assert _last_non_empty_line("a\n\nb\n") == "b"
 
@@ -59,6 +66,7 @@ def test_detect_interaction_selection(self):
 
 
 class TestModelsAndConstants:
+
     def test_exec_input_defaults(self):
         inp = ExecInput(skill="s", command="echo hi")
         assert inp.yield_time_ms == 0
@@ -73,6 +81,7 @@ def test_default_constants(self):
 
 
 class TestSessionStore:
+
     @pytest.mark.asyncio
     async def test_put_get_remove(self):
         tool = _make_exec_tool()
@@ -87,6 +96,7 @@ async def test_put_get_remove(self):
 
 
 class TestFactoryAndDeclarations:
+
     def test_create_exec_tools(self):
         run_tool = MagicMock()
         run_tool._repository = MagicMock()
@@ -105,6 +115,7 @@ def test_declaration_names(self):
 
 
 class TestCloseSession:
+
     @pytest.mark.asyncio
     async def test_close_session(self):
         sess = MagicMock()
@@ -113,6 +124,68 @@ async def test_close_session(self):
         sess.proc.close.assert_awaited_once()
 
 
+class TestExecutionEnvironment:
+
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize("tool_name", ["skill_run", "skill_exec"])
+    @pytest.mark.parametrize(
+        ("call_env", "host_env", "expected"),
+        [
+            pytest.param({}, None, "injected", id="repository"),
+            pytest.param({"TEST_SKILL_ENV": "explicit"}, None, "explicit", id="explicit"),
+            pytest.param({}, "host", "host", id="host"),
+            pytest.param({"TEST_SKILL_ENV": "explicit"}, "host", "explicit", id="explicit-over-host"),
+            pytest.param({}, "  ", "injected", id="blank-host"),
+            pytest.param({"TEST_SKILL_ENV": ""}, None, "", id="empty-explicit"),
+        ],
+    )
+    async def test_skill_tools_apply_repository_env(self, tmp_path, monkeypatch, tool_name, call_env, host_env,
+                                                    expected):
+        if host_env is None:
+            monkeypatch.delenv("TEST_SKILL_ENV", raising=False)
+        else:
+            monkeypatch.setenv("TEST_SKILL_ENV", host_env)
+
+        ctx = MagicMock()
+        ctx.agent_name = ""
+        ctx.actions.state_delta = {}
+        ctx.session_state = {}
+        ws = MagicMock(path=str(tmp_path))
+        workspace_runtime = MagicMock(spec=BaseWorkspaceRuntime)
+        workspace_runtime.manager.return_value.create_workspace = AsyncMock(return_value=ws)
+        workspace_runtime.fs.return_value.collect = AsyncMock(return_value=[])
+        runner = workspace_runtime.runner.return_value
+        runner.run_program = AsyncMock(return_value=WorkspaceRunResult(stdout="done", exit_code=0))
+        runner.start_program = AsyncMock(return_value=MagicMock())
+
+        repository = MagicMock()
+        repository.get_workspace_runtime.return_value = workspace_runtime
+        repository.skill_run_env.return_value = {"TEST_SKILL_ENV": "injected"}
+        run_tool = SkillRunTool(repository=repository)
+        run_tool.skill_stager.stage_skill = AsyncMock(return_value=SkillStageResult(workspace_skill_dir="skills/test"))
+        monkeypatch.setattr(_ExecSession, "yield_output", AsyncMock(return_value=("running", "", 0, 0)))
+        tool = run_tool if tool_name == "skill_run" else SkillExecTool(run_tool)
+
+        await tool._run_async_impl(
+            tool_context=ctx,
+            args={
+                "skill": " test ",
+                "command": "echo done",
+                "env": call_env
+            },
+        )
+
+        if tool_name == "skill_run":
+            env = runner.run_program.call_args.args[1].env
+            effective_env = os.environ.copy()
+            effective_env.update(env)
+        else:
+            effective_env = runner.start_program.call_args.args[2].env
+        assert effective_env["TEST_SKILL_ENV"] == expected
+        assert effective_env[ENV_SKILL_NAME] == "test"
+        repository.skill_run_env.assert_called_once_with("test")
+
+
 @pytest.mark.asyncio
 async def test_collect_final_result_passes_workspace_runtime_and_returns_files():
     ctx = MagicMock()

tests/skills/tools/test_skill_run.py

@@ -15,6 +15,7 @@
 from trpc_agent_sdk.skills.tools._skill_run import SkillRunInput
 from trpc_agent_sdk.skills.tools._skill_run import SkillRunOutput
 from trpc_agent_sdk.skills.tools._skill_run import SkillRunTool
+from trpc_agent_sdk.skills.tools._skill_run import _apply_skill_run_env
 from trpc_agent_sdk.skills.tools._skill_run import _build_editor_wrapper_script
 from trpc_agent_sdk.skills.tools._skill_run import _filter_failed_empty_outputs
 from trpc_agent_sdk.skills.tools._skill_run import _is_text_mime
@@ -32,6 +33,7 @@ def _make_tool() -> SkillRunTool:
 
 
 class TestSchemaHelpers:
+
     def test_inline_json_schema_refs(self):
         schema = {"$defs": {"X": {"type": "string"}}, "properties": {"x": {"$ref": "#/$defs/X"}}}
         out = inline_json_schema_refs(schema)
@@ -40,6 +42,54 @@ def test_inline_json_schema_refs(self):
 
 
 class TestModuleHelpers:
+
+    def test_apply_skill_run_env_filters_empty_entries(self, monkeypatch):
+        monkeypatch.delenv("TEST_SKILL_ENV", raising=False)
+        repository = MagicMock()
+        repository.skill_run_env.return_value = {
+            " TEST_SKILL_ENV ": " injected ",
+            "": "ignored",
+            "  ": "ignored",
+            "TEST_EMPTY_ENV": "  ",
+        }
+        env = {}
+
+        _apply_skill_run_env(repository, "test", env)
+
+        assert env == {"TEST_SKILL_ENV": " injected "}
+        repository.skill_run_env.assert_called_once_with("test")
+
+    @pytest.mark.parametrize(
+        "key",
+        [
+            "LD_PRELOAD",
+            "ld_preload",
+            "LD_LIBRARY_PATH",
+            "DYLD_INSERT_LIBRARIES",
+            "DYLD_LIBRARY_PATH",
+            "DYLD_FORCE_FLAT_NAMESPACE",
+            "OPENSSL_CONF",
+        ],
+    )
+    def test_apply_skill_run_env_blocks_loader_keys(self, monkeypatch, key):
+        monkeypatch.delenv(key, raising=False)
+        repository = MagicMock()
+        repository.skill_run_env.return_value = {key: "blocked"}
+        env = {}
+
+        _apply_skill_run_env(repository, "test", env)
+
+        assert env == {}
+
+    def test_apply_skill_run_env_ignores_repository_errors(self):
+        repository = MagicMock()
+        repository.skill_run_env.side_effect = RuntimeError("repository env unavailable")
+        env = {"TEST_SKILL_ENV": "explicit"}
+
+        _apply_skill_run_env(repository, "test", env)
+
+        assert env == {"TEST_SKILL_ENV": "explicit"}
+
     def test_is_text_mime(self):
         assert _is_text_mime("text/plain") is True
         assert _is_text_mime("application/json") is True
@@ -111,6 +161,7 @@ def test_build_editor_wrapper_script(self):
 
 
 class TestModels:
+
     def test_run_models(self):
         inp = SkillRunInput(skill="s", command="echo hi")
         out = SkillRunOutput()
@@ -121,6 +172,7 @@ def test_run_models(self):
 
 
 class TestSkillRunToolBasics:
+
     def test_resolve_cwd(self):
         tool = _make_tool()
         assert tool._resolve_cwd("", "skills/x") == "skills/x"

trpc_agent_sdk/skills/tools/_skill_exec.py

@@ -91,6 +91,7 @@
 from ._skill_run import SkillRunInput
 from ._skill_run import SkillRunOutput
 from ._skill_run import SkillRunTool
+from ._skill_run import _apply_skill_run_env
 from ._skill_run import _filter_failed_empty_outputs
 from ._skill_run import _select_primary_output
 from ._skill_run import _truncate_output
@@ -447,6 +448,7 @@ async def _run_async_impl(
         extra_env: dict[str, str] = dict(inputs.env)
         if ENV_SKILL_NAME not in extra_env:
             extra_env[ENV_SKILL_NAME] = normalized_skill
+        _apply_skill_run_env(repository, normalized_skill, extra_env)
         merged_env = _build_exec_env(ws, extra_env)
 
         # Start interactive program session via runtime runner.

trpc_agent_sdk/skills/tools/_skill_run.py

@@ -116,6 +116,25 @@
 # ---------------------------------------------------------------------------
 
 
+def _apply_skill_run_env(repository: BaseSkillRepository, skill_name: str, env: dict[str, str]) -> None:
+    """Inject skill-specific env without overriding explicit or non-empty host values."""
+    try:
+        skill_env: dict[str, str] = repository.skill_run_env(skill_name)
+        for k, v in skill_env.items():
+            k = k.strip()
+            if not k or not v.strip():
+                continue
+            if k in env:  # don't override explicit tool-call env
+                continue
+            if os.environ.get(k, "").strip():  # don't override host env
+                continue
+            if k.upper() in _BLOCKED_SKILL_ENV_KEYS:
+                continue
+            env[k] = v
+    except Exception:  # pylint: disable=broad-except
+        pass
+
+
 def _is_text_mime(mime: str) -> bool:
     """Return True when *mime* is a text-like content type."""
     if not mime:
@@ -770,21 +789,7 @@ async def _run_program(
 
         # Inject skill-specific env from repository (e.g. api_key → primary_env)
         repository = self._get_repository(ctx)
-        try:
-            skill_env: dict[str, str] = repository.skill_run_env(input_data.skill)
-            for k, v in skill_env.items():
-                k = k.strip()
-                if not k or not v.strip():
-                    continue
-                if k in env:  # don't override explicit tool-call env
-                    continue
-                if os.environ.get(k, "").strip():  # don't override host env
-                    continue
-                if k.upper() in _BLOCKED_SKILL_ENV_KEYS:
-                    continue
-                env[k] = v
-        except Exception:  # pylint: disable=broad-except
-            pass
+        _apply_skill_run_env(repository, input_data.skill, env)
 
         # Stage editor helper if requested
         await self._prepare_editor_env(ctx, ws, workspace_runtime, env, input_data.editor_text)