feature: 优化skill

- 本地沙箱环境注入文件支持软连接
- skill文件读取支持缓存

Author: raychen911

examples/skills/agent/tools.py

@@ -12,6 +12,7 @@
 from trpc_agent_sdk.code_executors import create_local_workspace_runtime
 from trpc_agent_sdk.skills import ENV_SKILLS_ROOT
 from trpc_agent_sdk.skills import SkillToolSet
+from trpc_agent_sdk.skills.tools import LinkCopySkillStager
 from trpc_agent_sdk.skills import create_default_skill_repository
 
 
@@ -46,5 +47,10 @@ def create_skill_tool_set() -> SkillToolSet:
     workspace_runtime_args = {}
     workspace_runtime = _create_workspace_runtime(**workspace_runtime_args)
     skill_paths = _get_skill_paths()
-    repository = create_default_skill_repository(skill_paths, workspace_runtime=workspace_runtime)
-    return SkillToolSet(repository=repository, run_tool_kwargs=tool_kwargs), repository
+    # use_cached_repository: Whether to use cached repository.
+    repository = create_default_skill_repository(skill_paths, workspace_runtime=workspace_runtime, 
+                                                 use_cached_repository=True)
+    skill_stager = LinkCopySkillStager()
+    # skill_stager: The stager to use for staging skills.
+    skill_toolset = SkillToolSet(repository=repository, run_tool_kwargs=tool_kwargs, skill_stager=skill_stager)
+    return skill_toolset, repository

tests/code_executors/local/test_local_ws_runtime.py

@@ -241,6 +241,36 @@ async def test_stage_directory(self):
         assert (dest / "file.txt").read_text() == "content"
         assert (dest / "sub" / "nested.txt").read_text() == "nested"
 
+    @pytest.mark.asyncio
+    async def test_stage_directory_link_mode(self):
+        src_dir = Path(self.tmpdir) / "source_link"
+        src_dir.mkdir()
+        (src_dir / "file.txt").write_text("content")
+        (src_dir / "sub").mkdir()
+        (src_dir / "sub" / "nested.txt").write_text("nested")
+
+        await self.fs.stage_directory(self.ws, str(src_dir), "dest_link", WorkspaceStageOptions(mode="link"))
+
+        dest = Path(self.tmpdir) / "dest_link"
+        assert dest.is_dir()
+        assert (dest / "file.txt").is_symlink()
+        assert (dest / "sub").is_symlink()
+        assert (dest / "file.txt").read_text() == "content"
+        assert (dest / "sub" / "nested.txt").read_text() == "nested"
+
+    @pytest.mark.asyncio
+    async def test_stage_directory_link_mode_keeps_root_mutable_for_stager_links(self):
+        src_dir = Path(self.tmpdir) / "source_link_root"
+        src_dir.mkdir()
+        (src_dir / "file.txt").write_text("content")
+
+        await self.fs.stage_directory(self.ws, str(src_dir), "dest_link_root", WorkspaceStageOptions(mode="link"))
+
+        dest = Path(self.tmpdir) / "dest_link_root"
+        (dest / "out").symlink_to("../out")
+        assert (dest / "out").is_symlink()
+        assert not (src_dir / "out").exists()
+
     @pytest.mark.asyncio
     async def test_stage_directory_read_only(self):
         src_dir = Path(self.tmpdir) / "src_ro"
@@ -462,25 +492,25 @@ async def test_fetch_bytes_budget_above_size(self):
         assert data == b"hello world"
         assert raw == 11
 
-    # --- _copy_directory ---
-    def test_copy_directory(self):
+    # --- _put_directory ---
+    def test_put_directory_copy_mode(self):
         src = Path(self.tmpdir) / "copy_src"
         src.mkdir()
         (src / "a.txt").write_text("a")
         (src / "sub").mkdir()
         (src / "sub" / "b.txt").write_text("b")
 
         dst = Path(self.tmpdir) / "copy_dst"
-        self.fs._copy_directory(str(src), str(dst))
+        self.fs._put_directory(self.ws, str(src), "copy_dst", mode="copy")
 
         assert (dst / "a.txt").read_text() == "a"
         assert (dst / "sub" / "b.txt").read_text() == "b"
 
-    def test_copy_directory_empty(self):
+    def test_put_directory_copy_mode_empty(self):
         src = Path(self.tmpdir) / "empty_src"
         src.mkdir()
         dst = Path(self.tmpdir) / "empty_dst"
-        self.fs._copy_directory(str(src), str(dst))
+        self.fs._put_directory(self.ws, str(src), "empty_dst", mode="copy")
         assert dst.exists()
 
     # --- _make_tree_read_only ---
@@ -551,8 +581,9 @@ async def test_stage_inputs_host_copy(self):
         specs = [WorkspaceInputSpec(src=f"host://{host_dir}", dst="work/inputs/data", mode="copy")]
         await self.fs.stage_inputs(self.ws, specs)
 
-        copied = Path(self.tmpdir) / "work" / "inputs"
-        assert copied.exists()
+        copied = Path(self.tmpdir) / "work" / "inputs" / "data"
+        assert copied.is_dir()
+        assert (copied / "data.txt").read_text() == "host data"
 
     @pytest.mark.asyncio
     async def test_stage_inputs_host_link(self):
@@ -564,7 +595,9 @@ async def test_stage_inputs_host_link(self):
         await self.fs.stage_inputs(self.ws, specs)
 
         linked = Path(self.tmpdir) / "work" / "inputs" / "linked"
-        assert linked.is_symlink() or linked.exists()
+        assert linked.is_dir()
+        assert (linked / "link.txt").is_symlink()
+        assert (linked / "link.txt").read_text() == "link data"
 
     @pytest.mark.asyncio
     async def test_stage_inputs_workspace(self):

tests/code_executors/test_types.py

@@ -294,17 +294,19 @@ class TestWorkspaceStageOptions:
 
     def test_create_workspace_stage_options(self):
         """Test creating workspace stage options."""
-        options = WorkspaceStageOptions(read_only=True, allow_mount=True)
+        options = WorkspaceStageOptions(read_only=True, allow_mount=True, mode="link")
 
         assert options.read_only is True
         assert options.allow_mount is True
+        assert options.mode == "link"
 
     def test_create_workspace_stage_options_defaults(self):
         """Test creating workspace stage options with defaults."""
         options = WorkspaceStageOptions()
 
         assert options.read_only is False
         assert options.allow_mount is False
+        assert options.mode == ""
 
 
 class TestWorkspaceCapabilities:

tests/skills/test_repository.py

@@ -26,6 +26,7 @@
 from trpc_agent_sdk.skills._repository import (
     BASE_DIR_PLACEHOLDER,
     BaseSkillRepository,
+    CachedFsSkillRepository,
     FsSkillRepository,
     create_default_skill_repository,
 )
@@ -203,6 +204,65 @@ def test_summaries(self, tmp_path):
         assert "a-skill" in names
         assert "b-skill" in names
 
+    def test_base_repository_reads_body_for_summaries(self, tmp_path):
+        _create_skill_dir(tmp_path, "summary-baseline", "Summary", body="# Large Body\n")
+        repo = FsSkillRepository(str(tmp_path))
+        original_read_text = Path.read_text
+
+        with patch.object(Path, "read_text", autospec=True, side_effect=original_read_text) as mock_read_text:
+            summaries = repo.summaries()
+
+        assert [summary.name for summary in summaries] == ["summary-baseline"]
+        assert mock_read_text.call_count == 1
+
+    def test_cached_repository_summaries_do_not_read_skill_body(self, tmp_path):
+        _create_skill_dir(tmp_path, "summary-only", "Summary", body="# Large Body\n")
+
+        with patch.object(Path, "read_text", side_effect=AssertionError("body should not be read")):
+            repo = CachedFsSkillRepository(str(tmp_path))
+            summaries = repo.summaries()
+
+        assert [summary.name for summary in summaries] == ["summary-only"]
+        assert summaries[0].description == "Summary"
+
+    def test_base_repository_does_not_reuse_skill_body(self, tmp_path):
+        _create_skill_dir(tmp_path, "uncached-skill", "Uncached", body="# Uncached Body\n")
+        repo = FsSkillRepository(str(tmp_path))
+        original_read_text = Path.read_text
+
+        with patch.object(Path, "read_text", autospec=True, side_effect=original_read_text) as mock_read_text:
+            repo.get("uncached-skill")
+            repo.get("uncached-skill")
+
+        assert mock_read_text.call_count == 2
+
+    def test_cached_repository_get_reuses_cached_skill_body(self, tmp_path):
+        _create_skill_dir(tmp_path, "cached-skill", "Cached", body="# Cached Body\n")
+        repo = CachedFsSkillRepository(str(tmp_path))
+        original_read_text = Path.read_text
+
+        with patch.object(Path, "read_text", autospec=True, side_effect=original_read_text) as mock_read_text:
+            first = repo.get("cached-skill")
+            second = repo.get("cached-skill")
+
+        assert first.body == second.body
+        assert mock_read_text.call_count == 1
+
+    def test_cached_repository_get_refreshes_cached_body_when_skill_file_changes(self, tmp_path):
+        skill_dir = _create_skill_dir(tmp_path, "mutable-skill", "Before", body="# Before\n")
+        skill_file = skill_dir / "SKILL.md"
+        repo = CachedFsSkillRepository(str(tmp_path))
+        first = repo.get("mutable-skill")
+
+        skill_file.write_text("---\nname: mutable-skill\ndescription: After\n---\n# After changed body\n",
+                              encoding="utf-8")
+
+        second = repo.get("mutable-skill")
+
+        assert "Before" in first.body
+        assert "After changed body" in second.body
+        assert second.summary.description == "After"
+
     def test_refresh(self, tmp_path):
         repo = FsSkillRepository(str(tmp_path))
         assert repo.skill_list() == []
@@ -311,6 +371,7 @@ class TestCreateDefaultSkillRepository:
     def test_creates_repository(self, tmp_path):
         _create_skill_dir(tmp_path, "test")
         repo = create_default_skill_repository(str(tmp_path))
+        assert isinstance(repo, CachedFsSkillRepository)
         assert isinstance(repo, FsSkillRepository)
         assert "test" in repo.skill_list()
 

trpc_agent_sdk/code_executors/_types.py

@@ -184,6 +184,9 @@ class WorkspaceStageOptions(BaseModel):
     allow_mount: bool = False
     """ whether to allow mount"""
 
+    mode: str = ""
+    """ staging mode hint, e.g. 'copy' or 'link'. Empty means runtime default."""
+
 
 class WorkspaceCapabilities(BaseModel):
     """

trpc_agent_sdk/code_executors/local/_local_ws_runtime.py

@@ -152,6 +152,13 @@ class LocalWorkspaceFS(BaseWorkspaceFS):
     def __init__(self, read_only_staged_skill: bool = False):
         self.read_only_staged_skill = read_only_staged_skill
 
+    @staticmethod
+    def _normalize_stage_mode(mode: str) -> str:
+        mode = (mode or "copy").strip().lower()
+        if mode not in {"copy", "link"}:
+            raise ValueError(f"unsupported local workspace stage mode: {mode!r}")
+        return mode
+
     @override
     async def put_files(
         self,
@@ -189,11 +196,15 @@ async def stage_directory(
             to: Destination path relative to workspace
             opt: Staging options
         """
-        self._put_directory(ws, src, dst)
+        mode = self._normalize_stage_mode(opt.mode)
+        self._put_directory(ws, src, dst, mode=mode)
 
         # Make tree read-only if requested
         ro = opt.read_only or self.read_only_staged_skill
-        if ro:
+        # Link mode uses symlinks to host files. chmod would follow symlinks on
+        # many platforms and mutate the source skill tree, so leave protection
+        # to the skill stager's symlink-aware chmod pass.
+        if ro and mode != "link":
             if dst:
                 dst = Path(ws.path) / Path(dst)
             else:
@@ -205,9 +216,10 @@ def _put_directory(
         ws: WorkspaceInfo,
         src: str,
         dst: str,
+        mode: str = "copy",
     ) -> None:
         """
-        Copy an entire directory from host into workspace.
+        Put a host path into workspace using copy or link mode.
 
         Args:
             ctx: Context for the operation
@@ -217,31 +229,44 @@ def _put_directory(
         """
         src = os.path.abspath(src)
         dst = path_join(ws.path, dst)
-        self._copy_directory(src, dst)
+        src_path = Path(src)
+        if mode == "link" and src_path.is_dir():
+            self._link_directory(src, dst)
+        elif mode == "link":
+            make_symlink(ws.path, os.path.relpath(dst, ws.path), src)
+        else:
+            copy_path(src, dst)
 
-    def _copy_directory(
+    def _link_directory(
         self,
         src: str,
         dst: str,
     ) -> None:
-        """Copy directory recursively.
+        """Stage a directory by symlinking its direct children.
 
-        Args:
-            src: Source directory path
-            dst: Destination directory path
+        The destination root is a real directory so later staging logic can add
+        workspace-local links such as ``out`` / ``work`` without mutating the
+        original skill directory. Direct child directories such as ``scripts``
+        or ``references`` are linked as directories to avoid walking large
+        skill trees.
         """
         src_path = Path(src)
         dst_path = Path(dst)
+        if dst_path.exists() or dst_path.is_symlink():
+            if dst_path.is_symlink() or dst_path.is_file():
+                dst_path.unlink()
+            elif not dst_path.is_dir():
+                raise ValueError(f"cannot stage into non-directory path: {dst}")
         dst_path.mkdir(parents=True, exist_ok=True)
 
-        for item in src_path.rglob("*"):
-            rel_path = item.relative_to(src)
-            target = dst_path / rel_path
-            if item.is_dir():
-                target.mkdir(parents=True, exist_ok=True)
-            else:
-                target.parent.mkdir(parents=True, exist_ok=True)
-                shutil.copy2(item, target)
+        for item in src_path.iterdir():
+            target = dst_path / item.name
+            if target.exists() or target.is_symlink():
+                if target.is_dir() and not target.is_symlink():
+                    shutil.rmtree(target)
+                else:
+                    target.unlink()
+            target.symlink_to(item.resolve(strict=False), target_is_directory=item.is_dir())
 
     def _make_tree_read_only(
         self,
@@ -401,31 +426,20 @@ async def stage_inputs(
                 # Handle host inputs
                 host_path = spec.src[len("host://"):]
                 resolved = host_path
-                if mode == "link":
-                    make_symlink(ws.path, dst.as_posix(), host_path)
-                else:
-                    self._put_directory(ws, host_path, dst.parent.as_posix())
+                self._put_directory(ws, host_path, dst.as_posix(), mode=mode)
             elif spec.src.startswith("workspace://"):
                 # Handle workspace inputs
                 rel = spec.src[len("workspace://"):]
                 src = path_join(ws.path, rel)
                 resolved = rel
-
-                if mode == "link":
-                    make_symlink(ws.path, dst.as_posix(), src)
-                else:
-                    copy_path(src, path_join(ws.path, dst.as_posix()))
+                self._put_directory(ws, src, dst.as_posix(), mode=mode)
             elif spec.src.startswith("skill://"):
                 # Handle skill inputs
                 rest = spec.src[len("skill://"):]
                 src_base = Path(ws.path) / DIR_SKILLS
                 src = path_join(src_base.as_posix(), rest)
                 resolved = src
-
-                if mode == "link":
-                    make_symlink(ws.path, dst.as_posix(), src)
-                else:
-                    copy_path(src, path_join(ws.path, dst.as_posix()))
+                self._put_directory(ws, src, dst.as_posix(), mode=mode)
             else:
                 raise ValueError(f"unsupported input: {spec.src}")
 

trpc_agent_sdk/skills/__init__.py

@@ -56,6 +56,7 @@
 from ._dynamic_toolset import DynamicSkillToolSet
 from ._registry import SkillRegistry
 from ._repository import BaseSkillRepository
+from ._repository import CachedFsSkillRepository
 from ._repository import FsSkillRepository
 from ._repository import VisibilityFilter
 from ._repository import create_default_skill_repository
@@ -135,6 +136,7 @@
     "DynamicSkillToolSet",
     "SkillRegistry",
     "BaseSkillRepository",
+    "CachedFsSkillRepository",
     "FsSkillRepository",
     "VisibilityFilter",
     "create_default_skill_repository",