sycommon-python-lib 0.2.4a7__py3-none-any.whl → 0.2.5a0__py3-none-any.whl

sycommon/agent/sandbox/file_ops.py

@@ -289,15 +289,26 @@ class FileOperationsMixin:
         self: "HTTPSandboxBackend",
         file_path: str,
         content: str,
+        *,
+        overwrite: bool = True,  # 默认允许覆盖，兼容 deepagents offload 场景
     ) -> WriteResult:
-        """写入文件"""
+        """写入文件
+
+        Args:
+            file_path: 文件路径。
+            content: 文件内容。
+            overwrite: 是否允许覆盖已有文件，默认 True（兼容 deepagents 0.6.3
+                SummarizationMiddleware offload 场景，如 /large_tool_results/ 和
+                /conversation_history/ 路径）。设为 False 时，文件已存在返回错误。
+        """
         try:
             self._ensure_synced_sync()
             SYLogger.info(f"[Sandbox] 写入文件: {file_path} ({len(content)} 字符)")
             result = self._post_sync(f"{SANDBOX_API_PREFIX}/write", {
                 "file_path": file_path,
                 "content": base64.b64encode(content.encode()).decode(),
-                "user_id": self.user_id
+                "user_id": self.user_id,
+                "overwrite": overwrite,
             })
             write_result = WriteResult(
                 error=result.get("error"),
@@ -317,16 +328,25 @@ class FileOperationsMixin:
         file_path: str,
         content: str,
         *,
+        overwrite: bool = True,  # 默认允许覆盖，兼容 deepagents offload 场景
         timeout: int = None,
     ) -> WriteResult:
-        """异步写入文件"""
+        """异步写入文件
+
+        Args:
+            file_path: 文件路径。
+            content: 文件内容。
+            overwrite: 是否允许覆盖已有文件，默认 True。
+            timeout: 请求超时时间。
+        """
         try:
             await self._ensure_synced_async()
             SYLogger.info(f"[Sandbox] 异步写入文件: {file_path} ({len(content)} 字符)")
             result = await self._post_async_with_failover(f"{SANDBOX_API_PREFIX}/write", {
                 "file_path": file_path,
                 "content": base64.b64encode(content.encode()).decode(),
-                "user_id": self.user_id
+                "user_id": self.user_id,
+                "overwrite": overwrite,
             }, timeout=timeout)
             write_result = WriteResult(
                 error=result.get("error"),

sycommon/middleware/sandbox.py

@@ -133,7 +133,20 @@ WORKSPACE_BASE = os.environ.get("SANDBOX_WORKSPACE", _default_workspace)
 # ============== 辅助函数 ==============
 
 def _build_init_script(workspace: str) -> str:
-    """构建 shell 初始化脚本（沙箱环境初始化 + 路径映射 + 资源限制）"""
+    """构建 shell 初始化脚本（沙箱环境初始化 + 路径映射 + 资源限制）
+
+    Linux/macOS: 使用 bash
+    Windows: 使用 PowerShell 兼容模式
+    """
+    if platform.system() == "Windows":
+        # Windows: 用 PowerShell 简化版（无 bash）
+        safe_workspace = workspace.replace("'", "''")
+        return f'''
+$env:SANDBOX_ROOT = '{safe_workspace}'
+$env:_SANDBOX_WORKSPACE = '{safe_workspace}'
+Set-Location '{safe_workspace}'
+'''
+
     safe_workspace = shlex.quote(workspace)
     return f'''
 # 沙箱环境初始化
@@ -232,10 +245,38 @@ async def aensure_subdirs(workspace: str, subdirs: list[str] = None):
     await asyncio.to_thread(_makedirs)
 
 
+def _to_virtual_path(abs_path: str, workspace: str) -> str:
+    """将本地绝对路径转换为 POSIX 虚拟路径（用于返回给客户端/LLM）。
+
+    始终返回 "/" 开头的 POSIX 格式路径，无论当前操作系统。
+    例: /Users/.../workspace/skills/foo.md → "/skills/foo.md"
+    """
+    from pathlib import PurePosixPath, PurePath
+    rel = PurePath(abs_path).relative_to(PurePath(workspace))
+    return "/" + str(PurePosixPath(*rel.parts))
+
+
+def _is_path_within(child: str, parent: str) -> bool:
+    """检查 child 路径是否在 parent 目录内，跨平台兼容。
+
+    使用 os.path.realpath 解析后比较，避免 os.sep 差异（Windows = \\，Linux = /）
+    以及 symlink 导致的逃逸。
+    """
+    child_resolved = os.path.realpath(child)
+    parent_resolved = os.path.realpath(parent)
+    return child_resolved.startswith(parent_resolved + os.sep) or child_resolved == parent_resolved
+
+
 def resolve_sandbox_path(path: str, workspace: str) -> str:
     """
     将沙箱路径解析到用户工作目录，实现路径隔离
 
+    跨平台兼容：
+    - 输入路径始终为 POSIX 格式（/skills/foo.md），来自客户端/LLM
+    - 输出路径为当前 OS 的本地格式（Linux: /data/.../skills/foo.md, Windows: C:/.../skills/foo.md）
+    - 使用 pathlib.PurePosixPath 标准化输入，避免 os.path.normpath 在 Windows 上
+      不正确处理 POSIX 前导 / 的问题
+
     所有路径（包括绝对路径）都会映射到用户工作目录下：
     - /skills/foo.md -> {workspace}/skills/foo.md
     - skills/foo.md -> {workspace}/skills/foo.md
@@ -244,28 +285,76 @@ def resolve_sandbox_path(path: str, workspace: str) -> str:
 
     同时防止路径遍历攻击，确保解析后的路径仍在工作目录内
     """
-    # 规范化路径
-    path = os.path.normpath(path)
+    from pathlib import PurePosixPath, Path
+
     workspace = os.path.normpath(workspace)
 
-    # 如果路径已经在工作目录内，直接返回
-    if path.startswith(workspace + os.sep) or path == workspace:
-        return path
+    # 如果路径已经是本地绝对路径且在 workspace 内，直接返回
+    path_normed = os.path.normpath(path)
+    if os.path.isabs(path_normed) and _is_path_within(path_normed, workspace):
+        return path_normed
 
-    # 移除开头的 / 使其成为相对路径
-    if os.path.isabs(path):
-        path = path.lstrip(os.sep)
+    # 输入是 POSIX 虚拟路径（如 /skills/foo.md），用 PurePosixPath 解析
+    # PurePosixPath 会自动去掉前导 / 得到相对部分
+    posix_path = PurePosixPath(path)
+    if posix_path.is_absolute():
+        # 去掉前导 / 得到相对路径字符串（如 skills/foo.md）
+        # parts[0] 是 '/'，取 parts[1:] 拼接
+        relative_str = str(PurePosixPath(*posix_path.parts[1:])) if len(posix_path.parts) > 1 else ""
+    else:
+        relative_str = str(posix_path)
 
-    # 拼接到工作目录
-    resolved = os.path.normpath(os.path.join(workspace, path))
+    # 用 os.path.join 拼接到本地 workspace（自动适配 os.sep）
+    resolved = os.path.normpath(os.path.join(workspace, relative_str))
 
     # 安全检查：确保最终路径在工作目录内
-    if not resolved.startswith(workspace + os.sep) and resolved != workspace:
+    if not _is_path_within(resolved, workspace):
         raise ValueError(f"Path traversal detected: {path}")
 
     return resolved
 
 
+# Windows 不支持 start_new_session 和 os.killpg，用条件常量
+_SUBPROCESS_NEW_SESSION = platform.system() != "Windows"
+
+
+def _kill_process_tree(process):
+    """杀掉进程及其子进程，跨平台兼容。
+
+    Linux/macOS: os.killpg 杀进程组（包括孙进程）
+    Windows: process.kill() 杀主进程
+    """
+    if platform.system() == "Windows":
+        try:
+            process.kill()
+        except (ProcessLookupError, PermissionError):
+            pass
+    else:
+        _kill_process_tree(process)
+
+
+def _build_execute_command(init_script: str, user_command: str) -> tuple[str, dict]:
+    """构建跨平台的执行命令。
+
+    Returns:
+        (full_command, kwargs) - 完整命令字符串和 subprocess 额外参数。
+    """
+    if platform.system() == "Windows":
+        # Windows: PowerShell 执行
+        full_command = f'''{init_script}
+{user_command}
+'''
+        return full_command, {"shell": True}
+    else:
+        # Linux/macOS: bash heredoc
+        full_command = f'''bash <<'COMMAND_EOF'
+{init_script}
+{user_command}
+COMMAND_EOF
+'''
+        return full_command, {}
+
+
 def setup_sandbox_handler(app: FastAPI, config: dict = None):
     """
     沙箱服务初始化
@@ -337,13 +426,8 @@ def setup_sandbox_handler(app: FastAPI, config: dict = None):
         # 使用统一初始化脚本
         init_script = _build_init_script(workspace)
 
-        # 使用 heredoc 格式执行命令，避免引号转义问题
-        # <<'COMMAND_EOF' 表示 heredoc 内容不进行变量展开，保护命令中的特殊字符
-        full_command = f'''bash <<'COMMAND_EOF'
-{init_script}
-{req.command}
-COMMAND_EOF
-'''
+        # 构建跨平台执行命令
+        full_command, _ = _build_execute_command(init_script, req.command)
 
         # 设置环境变量
         env = os.environ.copy()
@@ -360,7 +444,7 @@ COMMAND_EOF
                 stderr=asyncio.subprocess.PIPE,
                 cwd=workspace,
                 env=env,
-                start_new_session=True,
+                start_new_session=_SUBPROCESS_NEW_SESSION,
             )
 
             try:
@@ -373,10 +457,7 @@ COMMAND_EOF
                 stderr = stderr.decode('utf-8') if stderr else ''
             except asyncio.TimeoutError:
                 # 杀掉整个进程组（包括孙进程）
-                try:
-                    os.killpg(os.getpgid(process.pid), signal.SIGKILL)
-                except (ProcessLookupError, PermissionError):
-                    process.kill()
+                _kill_process_tree(process)
                 stdout, stderr = await process.communicate()
                 stdout = stdout.decode('utf-8') if stdout else ''
                 stderr = stderr.decode('utf-8') if stderr else ''
@@ -437,11 +518,7 @@ COMMAND_EOF
         await aensure_subdirs(workspace)
 
         init_script = _build_init_script(workspace)
-        full_command = f'''bash <<'COMMAND_EOF'
-{init_script}
-{req.command}
-COMMAND_EOF
-'''
+        full_command, _ = _build_execute_command(init_script, req.command)
 
         env = os.environ.copy()
         env["TMPDIR"] = os.path.join(workspace, "tmp")
@@ -457,7 +534,7 @@ COMMAND_EOF
                     stderr=asyncio.subprocess.PIPE,
                     cwd=workspace,
                     env=env,
-                    start_new_session=True,
+                    start_new_session=_SUBPROCESS_NEW_SESSION,
                 )
 
                 queue = asyncio.Queue()
@@ -492,10 +569,7 @@ COMMAND_EOF
                 try:
                     exit_code = await asyncio.wait_for(process.wait(), timeout=5)
                 except asyncio.TimeoutError:
-                    try:
-                        os.killpg(os.getpgid(process.pid), signal.SIGKILL)
-                    except (ProcessLookupError, PermissionError):
-                        process.kill()
+                    _kill_process_tree(process)
                     exit_code = -9
 
                 yield f"data: {json.dumps({'type': 'done', 'exit_code': exit_code})}\n\n"
@@ -523,11 +597,7 @@ COMMAND_EOF
         # 使用统一初始化脚本
         init_script = _build_init_script(workspace)
 
-        full_command = f'''bash <<'COMMAND_EOF'
-{init_script}
-{req.command}
-COMMAND_EOF
-'''
+        full_command, _ = _build_execute_command(init_script, req.command)
 
         env = os.environ.copy()
         env["TMPDIR"] = os.path.join(workspace, "tmp")
@@ -543,7 +613,7 @@ COMMAND_EOF
                 stderr=asyncio.subprocess.PIPE,
                 cwd=workspace,
                 env=env,
-                start_new_session=True,
+                start_new_session=_SUBPROCESS_NEW_SESSION,
             )
 
             async with lock:
@@ -571,10 +641,7 @@ COMMAND_EOF
                     stdout = stdout.decode('utf-8') if stdout else ''
                     stderr = stderr.decode('utf-8') if stderr else ''
                 except asyncio.TimeoutError:
-                    try:
-                        os.killpg(os.getpgid(process.pid), signal.SIGKILL)
-                    except (ProcessLookupError, PermissionError):
-                        process.kill()
+                    _kill_process_tree(process)
                     stdout, stderr = await process.communicate()
                     stdout = stdout.decode('utf-8') if stdout else ''
                     stderr = stderr.decode('utf-8') if stderr else ''
@@ -711,10 +778,7 @@ COMMAND_EOF
 
             # 在线程锁外执行 kill 操作（可能阻塞）
             try:
-                try:
-                    os.killpg(os.getpgid(process.pid), signal.SIGKILL)
-                except (ProcessLookupError, PermissionError):
-                    process.kill()
+                _kill_process_tree(process)
                 try:
                     await asyncio.wait_for(process.wait(), timeout=5)
                 except asyncio.TimeoutError:
@@ -770,10 +834,7 @@ COMMAND_EOF
         for pid, info in to_kill:
             process = info["process"]
             try:
-                try:
-                    os.killpg(os.getpgid(process.pid), signal.SIGKILL)
-                except (ProcessLookupError, PermissionError):
-                    process.kill()
+                _kill_process_tree(process)
                 try:
                     await asyncio.wait_for(process.wait(), timeout=5)
                 except asyncio.TimeoutError:
@@ -808,7 +869,11 @@ COMMAND_EOF
 
     @sandbox_router.post("/ls", response_model=list[FileInfo])
     async def ls_info(req: LsRequest):
-        """列出目录内容"""
+        """列出目录内容
+
+        安全增强（对齐 deepagents 0.6.3）：
+        - symlink 逃逸防护：结果路径 resolve 后必须在 workspace 内
+        """
         workspace = await aget_user_workspace(req.user_id)
         try:
             target_path = resolve_sandbox_path(req.path, workspace)
@@ -817,6 +882,7 @@ COMMAND_EOF
             return []
 
         def _ls():
+            workspace_resolved = os.path.realpath(workspace)
             if not os.path.isdir(target_path):
                 return None
             results = []
@@ -824,7 +890,14 @@ COMMAND_EOF
                 with os.scandir(target_path) as it:
                     for entry in it:
                         abs_path = os.path.join(target_path, entry.name)
-                        virtual_path = "/" + os.path.relpath(abs_path, workspace)
+                        # symlink 逃逸防护
+                        try:
+                            resolved = os.path.realpath(abs_path)
+                            if not _is_path_within(resolved, workspace_resolved):
+                                continue
+                        except OSError:
+                            continue
+                        virtual_path = _to_virtual_path(abs_path, workspace)
                         info = FileInfo(path=virtual_path)
                         try:
                             info.is_dir = entry.is_dir(follow_symlinks=False)
@@ -922,7 +995,12 @@ COMMAND_EOF
 
     @sandbox_router.post("/write", response_model=WriteResponse)
     async def write_file(req: WriteRequest):
-        """写入新文件（文件已存在时返回错误，应使用 edit 替代）"""
+        """写入文件
+
+        默认行为：文件不存在时创建新文件。
+        当 req.overwrite=True 时允许覆盖已有文件（用于 deepagents 内部 offload 场景，
+        如 /large_tool_results/ 和 /conversation_history/ 路径）。
+        """
         workspace = await aget_user_workspace(req.user_id)
         try:
             file_path = resolve_sandbox_path(req.file_path, workspace)
@@ -933,7 +1011,9 @@ COMMAND_EOF
         SYLogger.info(f"[Sandbox Server] 写入文件: {file_path}")
 
         def _write():
-            if os.path.exists(file_path):
+            # 允许覆盖模式（用于 deepagents offload 场景）
+            overwrite = getattr(req, 'overwrite', False)
+            if os.path.exists(file_path) and not overwrite:
                 SYLogger.warning(f"[Sandbox Server] 文件已存在: {file_path}")
                 return WriteResponse(error=f"Error: File already exists at {req.file_path}. Use edit_file to modify existing files.", path=None)
 
@@ -946,9 +1026,10 @@ COMMAND_EOF
             with open(file_path, 'w') as f:
                 f.write(content)
 
+            action = "覆盖" if (os.path.exists(file_path) and overwrite) else "新建"
             SYLogger.info(
-                f"[Sandbox Server] 写入成功(新建): {file_path} ({len(content)} 字符)")
-            virtual_path = "/" + os.path.relpath(file_path, workspace)
+                f"[Sandbox Server] 写入成功({action}): {file_path} ({len(content)} 字符)")
+            virtual_path = _to_virtual_path(file_path, workspace)
             return WriteResponse(error=None, path=virtual_path)
 
         try:
@@ -959,7 +1040,15 @@ COMMAND_EOF
 
     @sandbox_router.post("/edit", response_model=EditResponse)
     async def edit_file(req: EditRequest):
-        """编辑文件"""
+        """编辑文件
+
+        增强错误处理（对齐 deepagents 0.6.3 BaseSandbox）：
+        - os.stat + S_ISREG 精确判断文件类型
+        - try-except 包裹整个操作，捕获 FileNotFoundError/PermissionError
+        - CRLF 自动适配：匹配文件实际换行风格，保留原始行尾
+        """
+        import stat as stat_mod
+
         workspace = await aget_user_workspace(req.user_id)
         try:
             file_path = resolve_sandbox_path(req.file_path, workspace)
@@ -973,18 +1062,52 @@ COMMAND_EOF
             old_string = base64.b64decode(req.old_string).decode('utf-8')
             new_string = base64.b64decode(req.new_string).decode('utf-8')
 
-            if not os.path.isfile(file_path):
+            try:
+                st = os.stat(file_path)
+                if not stat_mod.S_ISREG(st.st_mode):
+                    SYLogger.error(f"[Sandbox Server] 编辑失败: 不是普通文件 {file_path}")
+                    return EditResponse(error="not_a_file")
+            except FileNotFoundError:
                 SYLogger.error(f"[Sandbox Server] 编辑失败: 文件不存在 {file_path}")
-                return EditResponse(error=f"File '{file_path}' not found")
+                return EditResponse(error="file_not_found")
+            except PermissionError:
+                SYLogger.error(f"[Sandbox Server] 编辑失败: 权限不足 {file_path}")
+                return EditResponse(error="permission_denied")
 
-            with open(file_path, 'r') as f:
-                content = f.read()
+            with open(file_path, 'rb') as f:
+                raw = f.read()
 
-            count = content.count(old_string)
+            try:
+                content = raw.decode('utf-8')
+            except UnicodeDecodeError:
+                SYLogger.error(f"[Sandbox Server] 编辑失败: 非文本文件 {file_path}")
+                return EditResponse(error="not_a_text_file")
+
+            # CRLF 自适应匹配（对齐 deepagents 0.6.3）：
+            # read endpoint 读取时会将 CRLF 转为 LF 给 LLM，
+            # 所以 old_string 到达时是 LF-only，但文件实际可能是 CRLF。
+            # 尝试多种变体，第一个匹配的揭示了文件在该区域的换行风格。
+            old_crlf = old_string.replace('\r\n', '\n').replace('\n', '\r\n')
+            old_lf = old_string.replace('\r\n', '\n')
+            new_crlf = new_string.replace('\r\n', '\n').replace('\n', '\r\n')
+            new_lf = new_string.replace('\r\n', '\n')
+
+            matched_old, matched_new, count = old_string, new_string, 0
+            for cand_old, cand_new in (
+                (old_string, new_string),
+                (old_crlf, new_crlf),
+                (old_lf, new_lf),
+            ):
+                c = content.count(cand_old)
+                if c >= 1:
+                    matched_old, matched_new, count = cand_old, cand_new, c
+                    break
 
             if count == 0:
-                SYLogger.error(f"[Sandbox Server] 编辑失败: 未找到匹配字符串")
-                return EditResponse(error=f"String not found: '{old_string[:50]}...'")
+                SYLogger.error("[Sandbox Server] 编辑失败: 未找到匹配字符串")
+                return EditResponse(
+                    error=f"String not found: '{old_string[:50]}...'"
+                )
             if count > 1 and not req.replace_all:
                 SYLogger.error(f"[Sandbox Server] 编辑失败: 多处匹配 ({count}次)")
                 return EditResponse(
@@ -992,15 +1115,15 @@ COMMAND_EOF
                 )
 
             if req.replace_all:
-                new_content = content.replace(old_string, new_string)
+                new_content = content.replace(matched_old, matched_new)
             else:
-                new_content = content.replace(old_string, new_string, 1)
+                new_content = content.replace(matched_old, matched_new, 1)
 
-            with open(file_path, 'w') as f:
-                f.write(new_content)
+            with open(file_path, 'wb') as f:
+                f.write(new_content.encode('utf-8'))
 
             SYLogger.info(f"[Sandbox Server] 编辑成功: {file_path} (替换 {count} 处)")
-            virtual_path = "/" + os.path.relpath(file_path, workspace)
+            virtual_path = _to_virtual_path(file_path, workspace)
             return EditResponse(error=None, path=virtual_path, occurrences=count)
 
         try:
@@ -1159,7 +1282,7 @@ COMMAND_EOF
                 for entry in entries:
 
                     abs_path = os.path.join(dir_path, entry.name)
-                    virtual_path = "/" + os.path.relpath(abs_path, workspace)
+                    virtual_path = _to_virtual_path(abs_path, workspace)
                     file_count += 1
 
                     try:
@@ -1181,7 +1304,7 @@ COMMAND_EOF
 
                 return node
 
-            root_virtual = "/" + os.path.relpath(target_path, workspace)
+            root_virtual = _to_virtual_path(target_path, workspace)
             return build_tree(target_path, root_virtual, 0)
 
         try:
@@ -1197,7 +1320,12 @@ COMMAND_EOF
 
     @sandbox_router.post("/glob", response_model=list[FileInfo])
     async def glob_files(req: GlobRequest):
-        """glob 搜索文件"""
+        """glob 搜索文件
+
+        增强错误处理（对齐 deepagents 0.6.3 BaseSandbox）：
+        - FileNotFoundError / NotADirectoryError / PermissionError 捕获
+        - os.stat 异常时跳过单个条目
+        """
         import glob as glob_module
 
         workspace = await aget_user_workspace(req.user_id)
@@ -1210,17 +1338,32 @@ COMMAND_EOF
         full_pattern = os.path.join(search_path, req.pattern)
 
         def _glob():
-            matches = sorted(glob_module.glob(full_pattern, recursive=True))
+            workspace_resolved = os.path.realpath(workspace)
+            try:
+                matches = sorted(glob_module.glob(full_pattern, recursive=True))
+            except (FileNotFoundError, NotADirectoryError, PermissionError) as e:
+                SYLogger.warning(f"[Sandbox Server] glob 异常: {e}")
+                return []
+
             results = []
             for m in matches:
-                virtual_path = "/" + os.path.relpath(m, workspace)
+                # 路径安全检查：跳过逃逸出 workspace 的 symlink
+                try:
+                    if not _is_path_within(m, workspace_resolved):
+                        SYLogger.warning(f"[Sandbox Server] glob 跳过逃逸路径: {m}")
+                        continue
+                except OSError:
+                    continue
+
+                virtual_path = _to_virtual_path(m, workspace)
                 info = FileInfo(path=virtual_path)
                 try:
+                    st = os.stat(m)
                     info.is_dir = os.path.isdir(m)
                     if not info.is_dir:
-                        info.size = os.path.getsize(m)
-                except Exception:
-                    pass
+                        info.size = st.st_size
+                except OSError:
+                    continue
                 results.append(info)
             return results
 
@@ -1228,7 +1371,13 @@ COMMAND_EOF
 
     @sandbox_router.post("/grep", response_model=list[GrepMatch])
     async def grep_search(req: GrepRequest):
-        """grep 搜索内容"""
+        """grep 搜索内容
+
+        安全增强（对齐 deepagents 0.6.3 backends/filesystem.py）：
+        - symlink 逃逸防护：结果路径必须 resolve 到 workspace 内
+        - 路径规范化：统一转换为虚拟路径，防止泄露宿主绝对路径
+        - 结果解析全量异步：os.path.realpath/relpath 通过 asyncio.to_thread 执行
+        """
         workspace = await aget_user_workspace(req.user_id)
         try:
             search_path = resolve_sandbox_path(req.path or "/", workspace)
@@ -1250,44 +1399,56 @@ COMMAND_EOF
             cmd,
             stdout=asyncio.subprocess.PIPE,
             stderr=asyncio.subprocess.PIPE,
-            start_new_session=True,
+            start_new_session=_SUBPROCESS_NEW_SESSION,
         )
         stdout, _ = await proc.communicate()
         result_text = stdout.decode('utf-8') if stdout else ''
 
-        matches = []
-        for line in result_text.strip().split("\n"):
-            if not line:
-                continue
-            # 使用更稳健的解析方式：找到第一个冒号（行号前）和第二个冒号（内容前）
-            # 先获取行号和内容部分（路径:path:line:text）
-            # 格式: path:line:text（text 可能包含冒号）
-            first_colon = line.find(":")
-            if first_colon == -1:
-                continue
-            second_colon = line.find(":", first_colon + 1)
-            if second_colon == -1:
-                continue
-
-            path_part = line[:first_colon]
-            # 将绝对路径转换为虚拟路径
-            try:
-                virtual_path_part = "/" + os.path.relpath(path_part, workspace)
-            except ValueError:
-                virtual_path_part = path_part
-            try:
-                line_num = int(line[first_colon + 1:second_colon])
-            except ValueError:
-                continue
-            text_part = line[second_colon + 1:]
+        # 结果解析（含 os.path.realpath / relpath 同步 IO）放入线程池
+        def _parse_grep_results():
+            workspace_resolved = os.path.realpath(workspace)
+            matches = []
+            for line in result_text.strip().split("\n"):
+                if not line:
+                    continue
+                first_colon = line.find(":")
+                if first_colon == -1:
+                    continue
+                second_colon = line.find(":", first_colon + 1)
+                if second_colon == -1:
+                    continue
+
+                path_part = line[:first_colon]
+
+                # 路径安全检查（对齐 deepagents 0.6.3）：
+                # resolve 后必须在 workspace 内，跳过 symlink 逃逸的结果
+                try:
+                    resolved = os.path.realpath(path_part)
+                    if not _is_path_within(resolved, workspace_resolved):
+                        SYLogger.warning(f"[Sandbox Server] grep 跳过逃逸路径: {path_part}")
+                        continue
+                except OSError:
+                    continue
+
+                # 将绝对路径转换为虚拟路径
+                try:
+                    virtual_path_part = _to_virtual_path(path_part, workspace)
+                except ValueError:
+                    virtual_path_part = path_part
+                try:
+                    line_num = int(line[first_colon + 1:second_colon])
+                except ValueError:
+                    continue
+                text_part = line[second_colon + 1:]
 
-            matches.append(GrepMatch(
-                path=virtual_path_part,
-                line=line_num,
-                text=text_part
-            ))
+                matches.append(GrepMatch(
+                    path=virtual_path_part,
+                    line=line_num,
+                    text=text_part
+                ))
+            return matches
 
-        return matches
+        return await asyncio.to_thread(_parse_grep_results)
 
     @sandbox_router.post("/stat", response_model=StatResponse)
     async def stat_file(req: StatRequest):
@@ -1298,7 +1459,7 @@ COMMAND_EOF
         except ValueError as e:
             return StatResponse(error=str(e))
 
-        virtual_path = "/" + os.path.relpath(target_path, workspace)
+        virtual_path = _to_virtual_path(target_path, workspace)
 
         def _stat():
             if not os.path.exists(target_path):
@@ -1337,7 +1498,7 @@ COMMAND_EOF
             try:
                 for item in os.listdir(target_path):
                     item_path = os.path.join(target_path, item)
-                    virtual_path = "/" + os.path.relpath(item_path, workspace)
+                    virtual_path = _to_virtual_path(item_path, workspace)
                     info = FileInfo(path=virtual_path)
                     try:
                         info.is_dir = os.path.isdir(item_path)
@@ -1366,8 +1527,7 @@ COMMAND_EOF
                                     return LsResponse(files=files, warning=f"Results truncated at {MAX_FILES} files")
 
                                 filepath = os.path.join(root, filename)
-                                virtual_filepath = "/" + \
-                                    os.path.relpath(filepath, workspace)
+                                virtual_filepath = _to_virtual_path(filepath, workspace)
                                 file_info = FileInfo(path=virtual_filepath)
                                 try:
                                     file_info.is_dir = False
@@ -1537,7 +1697,7 @@ COMMAND_EOF
                     continue
 
                 is_dir = new[2] if new else (old[2] if old else False)
-                virtual = "/" + os.path.relpath(os.path.join(target_path, p), workspace)
+                virtual = _to_virtual_path(os.path.join(target_path, p), workspace)
                 events.append(WatchEvent(event_type=evt, path=virtual, is_dir=is_dir))
 
             with open(snapshot_file, 'w') as f:

sycommon/middleware/tool_result_truncation.py

@@ -8,6 +8,10 @@
 
 同时处理 list 类型 content（如 read_file 读取图片返回的 base64 数据），
 将其转换为字符串描述，防止上游 API 拒绝 list content 的 400 错误。
+
+head+tail 预览模式（对齐 deepagents 0.6.3 _message_eviction）：
+截断时保留内容头部和尾部若干行，中间用行数提示替代，
+帮助模型了解整体结构而不必 read_file 恢复全部内容。
 """
 
 from collections.abc import Awaitable, Callable
@@ -36,18 +40,68 @@ DEFAULT_PASSTHROUGH_TOOLS: FrozenSet[str] = frozenset({
     "web_search",  # web_search 已在工具内部自行截断
 })
 
-# 截断提示模板
-DEFAULT_TRUNCATION_SUFFIX = (
-    "\n\n[输出已截断至前{kept}字符，原始长度{original}字符。"
+# head+tail 预览截断模板（对齐 deepagents 0.6.3 TOO_LARGE_TOOL_MSG 风格）
+HEAD_TAIL_TRUNCATION_TEMPLATE = (
+    "[输出已截断，原始长度 {original} 字符 / {original_lines} 行。]"
+    "\n\n以下是输出的头部和尾部预览（中间省略的行用 `... [N lines truncated] ...` 标记）：\n\n"
+    "{preview}\n\n"
     "如需查看完整输出，可以：\n"
     "1. 重新执行命令并添加过滤条件（如 grep、head、tail）\n"
-    "2. 将输出重定向到文件后用 read_file 分段读取]"
+    "2. 将输出重定向到文件后用 read_file 分段读取（使用 offset 和 limit 参数）"
 )
 
 # list 类型 content 中 base64 图片的最大字符数
 MAX_IMAGE_BASE64_CHARS = 500
 
 
+def _create_head_tail_preview(
+    content: str,
+    *,
+    head_lines: int = 10,
+    tail_lines: int = 10,
+    max_line_chars: int = 200,
+) -> str:
+    """创建 head+tail 预览，中间用行数提示替代。
+
+    对齐 deepagents 0.6.3 的 _create_content_preview 逻辑：
+    - 保留头部和尾部若干行
+    - 每行截断到 max_line_chars 防止单行爆炸
+    - 中间用 `... [N lines truncated] ...` 标记
+    - 附带行号帮助模型定位
+
+    Args:
+        content: 原始内容。
+        head_lines: 保留头部行数。
+        tail_lines: 保留尾部行数。
+        max_line_chars: 每行最大字符数。
+
+    Returns:
+        格式化后的预览字符串。
+    """
+    lines = content.splitlines()
+    total = len(lines)
+
+    if total <= head_lines + tail_lines + 5:
+        # 内容足够短，直接返回（每行截断）
+        return "\n".join(line[:max_line_chars] for line in lines)
+
+    head = [line[:max_line_chars] for line in lines[:head_lines]]
+    tail = [line[:max_line_chars] for line in lines[-tail_lines:]]
+    omitted = total - head_lines - tail_lines
+
+    head_with_nums = []
+    for i, line in enumerate(head, start=1):
+        head_with_nums.append(f"{i:6d} | {line}")
+
+    truncation_marker = f"\n... [{omitted} lines truncated] ...\n"
+
+    tail_with_nums = []
+    for i, line in enumerate(tail, start=total - tail_lines + 1):
+        tail_with_nums.append(f"{i:6d} | {line}")
+
+    return "\n".join(head_with_nums) + truncation_marker + "\n".join(tail_with_nums)
+
+
 def _convert_list_content_to_str(content: list, tool_name: str) -> str:
     """将 list 类型的 ToolMessage.content 转换为字符串。
 
@@ -80,12 +134,18 @@ def _convert_list_content_to_str(content: list, tool_name: str) -> str:
 class ToolResultTruncationMiddleware(AgentMiddleware):
     """截断过长的工具结果，防止超出模型上下文窗口。
 
+    采用 head+tail 预览模式（对齐 deepagents 0.6.3 _message_eviction）：
+    - 保留内容头部和尾部若干行
+    - 中间省略部分用行数标记替代
+    - 附带行号帮助模型定位和恢复
+
     Args:
         max_content_length: 工具结果内容的最大字符长度，默认 15000（约 3750 token）。
             模型上下文 200K token，70% 触发压缩 = 140K token，给单条工具结果留 3750 token
             约占剩余空间的 2.6%，多条工具调用并行时也不会逼近上限。
         passthrough_tools: 不截断的工具名集合。
-        truncation_suffix: 截断提示文本，支持 {kept} 和 {original} 占位符。
+        head_lines: 截断时保留的头部行数，默认 10。
+        tail_lines: 截断时保留的尾部行数，默认 10。
     """
 
     def __init__(
@@ -93,11 +153,13 @@ class ToolResultTruncationMiddleware(AgentMiddleware):
         *,
         max_content_length: int = 15000,
         passthrough_tools: FrozenSet[str] | None = None,
-        truncation_suffix: str = DEFAULT_TRUNCATION_SUFFIX,
+        head_lines: int = 10,
+        tail_lines: int = 10,
     ) -> None:
         self._max_content_length = max_content_length
         self._passthrough_tools = passthrough_tools or DEFAULT_PASSTHROUGH_TOOLS
-        self._truncation_suffix = truncation_suffix
+        self._head_lines = head_lines
+        self._tail_lines = tail_lines
 
     @property
     def name(self) -> str:
@@ -114,13 +176,32 @@ class ToolResultTruncationMiddleware(AgentMiddleware):
         if original_len <= self._max_content_length:
             return content
 
-        kept = self._max_content_length
-        suffix = self._truncation_suffix.format(kept=kept, original=original_len)
-        truncated = content[:kept] + suffix
+        # head+tail 预览模式
+        preview = _create_head_tail_preview(
+            content,
+            head_lines=self._head_lines,
+            tail_lines=self._tail_lines,
+        )
+        original_lines = len(content.splitlines())
+        truncated = HEAD_TAIL_TRUNCATION_TEMPLATE.format(
+            original=original_len,
+            original_lines=original_lines,
+            preview=preview,
+        )
+
+        # 最终安全兜底：如果 head+tail 拼出来还是超长，硬截断
+        if len(truncated) > self._max_content_length * 2:
+            kept = self._max_content_length
+            truncated = content[:kept] + (
+                f"\n\n[输出已截断至前{kept}字符，原始长度{original_len}字符。"
+                "如需查看完整输出，可以：\n"
+                "1. 重新执行命令并添加过滤条件（如 grep、head、tail）\n"
+                "2. 将输出重定向到文件后用 read_file 分段读取]"
+            )
 
         SYLogger.info(
             f"[ToolResultTruncation] tool='{tool_name}' truncated: "
-            f"{original_len} -> {len(truncated)} chars"
+            f"{original_len} -> {len(truncated)} chars (head+tail preview)"
         )
         return truncated
 

sycommon/models/sandbox.py

@@ -138,6 +138,7 @@ class WriteRequest(BaseModel):
     file_path: str
     content: str  # base64 encoded
     user_id: str
+    overwrite: bool = False  # 是否允许覆盖已有文件（用于 offload 场景）
 
 
 class WriteResponse(BaseModel):

{sycommon_python_lib-0.2.4a7.dist-info → sycommon_python_lib-0.2.5a0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sycommon-python-lib
-Version: 0.2.4a7
+Version: 0.2.5a0
 Summary: Add your description here
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -8,8 +8,8 @@ Requires-Dist: aio-pika>=9.6.2
 Requires-Dist: aiohttp>=3.13.5
 Requires-Dist: aiomysql>=0.3.2
 Requires-Dist: anyio>=4.12.1
-Requires-Dist: decorator>=5.3.0
-Requires-Dist: deepagents>=0.6.1
+Requires-Dist: decorator>=5.3.1
+Requires-Dist: deepagents>=0.6.3
 Requires-Dist: elasticsearch>=9.4.0
 Requires-Dist: fastapi>=0.136.1
 Requires-Dist: jinja2>=3.1.6

{sycommon_python_lib-0.2.4a7.dist-info → sycommon_python_lib-0.2.5a0.dist-info}/RECORD

@@ -136,7 +136,7 @@ sycommon/agent/mcp/__init__.py,sha256=iKrdDhIrFsNIkqG_kgcwNe-nOiM6uVfolKv44LfQ-F
 sycommon/agent/mcp/models.py,sha256=RBAIbGETNXkqD3wQZT7eKS4ozkgE9DQEneF1WKZf1C0,1355
 sycommon/agent/mcp/tool_loader.py,sha256=SEny14f7Bm9I17pT-9PJWMbhi9Ki77wvCR0KRNEJmyM,6428
 sycommon/agent/sandbox/__init__.py,sha256=jR7LlkD4J4Y6QYyRXQClkwmqDBCCPmycV_hQV9p9YHw,4621
-sycommon/agent/sandbox/file_ops.py,sha256=6ymRMM0WchM7G_YmF1ckrLjf5s_JCh1wrAp2g_-sg8k,23162
+sycommon/agent/sandbox/file_ops.py,sha256=0PEhmK1OcMq1Qe33JmQwphj670Tih7HQLNuAb1snIjI,24028
 sycommon/agent/sandbox/http_sandbox_backend.py,sha256=kwuPEmrOMyxfrRu20AEGqWD9t38L-DrtKSFp6CWt44o,56877
 sycommon/agent/sandbox/minio_sync.py,sha256=d1kuWllvyAvAMsFZCP0OdHEQtXN9BEIgHbupC31BjSk,20000
 sycommon/agent/sandbox/sandbox_pool.py,sha256=eMn8sLakCWf90l6ni2-333QM8oBdX1CflV-WzneFp_k,9133
@@ -203,10 +203,10 @@ sycommon/middleware/exception.py,sha256=UAy0tKijI_2JoKjwT3h62aL-tybftP3IETvcr26N
 sycommon/middleware/middleware.py,sha256=z3-6KHdBt93TOSNn0LY579WReSCo0o4f9d9-dq7c-ic,1600
 sycommon/middleware/monitor_memory.py,sha256=pYRK-wRuDd6enSg9Pf8tQxPdYQS6S0AyjyXeKFRLKEs,628
 sycommon/middleware/mq.py,sha256=9X6KKtadFjBXKS5L3kEKujYio9wwGfWgXwWOAHO-HDg,254
-sycommon/middleware/sandbox.py,sha256=SQnUvVE0gvBo_YrP4fdA-6ZmJxAG9Po1zUynNFrgTI4,61109
+sycommon/middleware/sandbox.py,sha256=DPvG1PhR57O4azvekS1C3XZ-lsS6yvOI5BKDDza9deI,68216
 sycommon/middleware/timeout.py,sha256=KlxOPa8xl2dg6yuRi_EzkVJG8bX4stb5ueYxctzzGM8,1433
 sycommon/middleware/token_tracking.py,sha256=rEbgV1bgWMdzAERx4aq5XAvOIT6jTY_tK1P0xHJnL3o,6609
-sycommon/middleware/tool_result_truncation.py,sha256=1IfhEwrOHzeSS-MB-43EOts2V_KYAq4T_utvqkhTdbE,7005
+sycommon/middleware/tool_result_truncation.py,sha256=C5739a3HkpiEPLplTnBTGcVOUvkd-lQBl3oYsM0_7rI,10129
 sycommon/middleware/traceid.py,sha256=HX4zg7Tp_mPNr2eWDDvK3f7GFJ6eOSeW062Xcc-xshc,14340
 sycommon/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sycommon/models/base_http.py,sha256=EICAAibx3xhjBsLqm35Mi3DCqxp0FME4rD_3iQVjT_E,3051
@@ -214,7 +214,7 @@ sycommon/models/log.py,sha256=rZpj6VkDRxK3B6H7XSeWdYZshU8F0Sks8bq1p6pPlDw,500
 sycommon/models/mqlistener_config.py,sha256=japihb4kmP5ZqvqQEs6C7CmcrPlE1UmhAtCimoL61xI,1704
 sycommon/models/mqmsg_model.py,sha256=Zo-LsDMFuF1Vkx9ZmwBC9E7TrCw-7nAQD2TE4v9-6F4,291
 sycommon/models/mqsend_config.py,sha256=NQX9dc8PpuquMG36GCVhJe8omAW1KVXXqr6lSRU6D7I,268
-sycommon/models/sandbox.py,sha256=5QPLqKCDm0UeyC8CHb2G0d7Rb3f7MYaLq12RFRSeOxc,7293
+sycommon/models/sandbox.py,sha256=bW273k59UndtAgUTQEIrZ4oL_ZaaO0pco1THtU_dj2M,7382
 sycommon/models/sso_user.py,sha256=uqLlZevVaDQQche5eBq8m1b8lu-45Pe4vHY3kd3NdxA,2896
 sycommon/models/token_usage.py,sha256=w3Aash7jUVSUIgKxBUzI6SqJ9VV5Pk7rLBbMUlLv6nA,1242
 sycommon/models/token_usage_mysql.py,sha256=eWnCvI2FDwyTA_fr4wWQtAmUnFJgLwrt0WXMXHLAESQ,2633
@@ -265,8 +265,8 @@ sycommon/tools/syemail.py,sha256=BDFhgf7WDOQeTcjxJEQdu0dQhnHFPO_p3eI0-Ni3LhQ,561
 sycommon/tools/timing.py,sha256=OiiE7P07lRoMzX9kzb8sZU9cDb0zNnqIlY5pWqHcnkY,2064
 sycommon/xxljob/__init__.py,sha256=7eoBlQxv-B39IfRSCY2bkqdGYs1QRe1umAWd88VMEEM,86
 sycommon/xxljob/xxljob_service.py,sha256=JIEJaGXhqrTLcyxlyynSrsHg9bBnDNzX-D4qIWLRPUE,6815
-sycommon_python_lib-0.2.4a7.dist-info/METADATA,sha256=ReaCw3hM57OWF1Gso6vD-CXssScGQMrJl3f7u78z0uM,7879
-sycommon_python_lib-0.2.4a7.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-sycommon_python_lib-0.2.4a7.dist-info/entry_points.txt,sha256=gsR4SssKxDWjRU8ggidzNcdMXDPRSKRS7UaGyNP84Qg,92
-sycommon_python_lib-0.2.4a7.dist-info/top_level.txt,sha256=RgphKrg7nJyZ7irJqbxFr-5H2LUYTvI7ivoWZH2hcD0,29
-sycommon_python_lib-0.2.4a7.dist-info/RECORD,,
+sycommon_python_lib-0.2.5a0.dist-info/METADATA,sha256=Nr9thCmAZmPdc2M2phRRYCQ6rOCzvak_fQd42DuWaRM,7879
+sycommon_python_lib-0.2.5a0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+sycommon_python_lib-0.2.5a0.dist-info/entry_points.txt,sha256=gsR4SssKxDWjRU8ggidzNcdMXDPRSKRS7UaGyNP84Qg,92
+sycommon_python_lib-0.2.5a0.dist-info/top_level.txt,sha256=RgphKrg7nJyZ7irJqbxFr-5H2LUYTvI7ivoWZH2hcD0,29
+sycommon_python_lib-0.2.5a0.dist-info/RECORD,,