sycommon-python-lib 0.2.7a56__tar.gz → 0.2.8a1__tar.gz

{sycommon_python_lib-0.2.7a56 → sycommon_python_lib-0.2.8a1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sycommon-python-lib
-Version: 0.2.7a56
+Version: 0.2.8a1
 Summary: Add your description here
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -9,11 +9,11 @@ Requires-Dist: aiohttp==3.14.3
 Requires-Dist: aiomysql==0.3.2
 Requires-Dist: anyio==4.14.2
 Requires-Dist: decorator==5.3.1
-Requires-Dist: deepagents==0.7.1
-Requires-Dist: elasticsearch==9.4.1
+Requires-Dist: deepagents==0.7.4
+Requires-Dist: elasticsearch==9.5.0
 Requires-Dist: fastapi==0.141.1
 Requires-Dist: jinja2==3.1.6
-Requires-Dist: kafka-python==3.0.9
+Requires-Dist: kafka-python==3.0.10
 Requires-Dist: langchain==1.3.14
 Requires-Dist: langchain-core==1.5.3
 Requires-Dist: langchain-openai==1.4.1

{sycommon_python_lib-0.2.7a56 → sycommon_python_lib-0.2.8a1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sycommon-python-lib"
-version = "0.2.7a56"
+version = "0.2.8a1"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -10,11 +10,11 @@ dependencies = [
     "aiomysql==0.3.2",
     "anyio==4.14.2",
     "decorator==5.3.1",
-    "deepagents==0.7.1",
-    "elasticsearch==9.4.1",
+    "deepagents==0.7.4",
+    "elasticsearch==9.5.0",
     "fastapi==0.141.1",
     "jinja2==3.1.6",
-    "kafka-python==3.0.9",
+    "kafka-python==3.0.10",
     "langchain==1.3.14",
     "langchain-core==1.5.3",
     "langchain-openai==1.4.1",

{sycommon_python_lib-0.2.7a56 → sycommon_python_lib-0.2.8a1}/src/sycommon/agent/deep_agent.py

@@ -160,6 +160,10 @@ class AgentConfig(BaseModel):
     # (scoped 由服务端路由硬编码,user 由 MinIO 按 user 灌入)。
     system_skills_allow: Optional[set[str]] = None
     memory_dir: Optional[str] = None
+    # 额外 middleware（应用层注入，如技能使用上报、自定义拦截）：
+    # 数字员工等项目自定义 AgentMiddleware 实例列表，create_deep_agent 会
+    # 追加到内置 middleware_list 之后执行。类型用 list 而非具体类避免循环依赖。
+    extra_middleware: list = []
 
     @property
     def skills_dir(self) -> Optional[str]:
@@ -1118,6 +1122,9 @@ async def create_deep_agent(
         SkillWriteGuardMiddleware(),          # 系统 /skills/system 只读守卫(先于白名单)
         SandboxPathGuardMiddleware(user_id),  # 宿主绝对路径规范化/拦截(防越权读他人沙箱文件)
     ]
+    # 应用层注入的额外 middleware（如技能使用上报），排在内置之后
+    if config.extra_middleware:
+        middleware_list.extend(config.extra_middleware)
 
     # RubricMiddleware：复用 FilesystemMiddleware 的工具（底层走 HTTPSandboxBackend HTTP 远程调用）
     if config.rubric_max_iterations > 0 and sandbox_backend:

{sycommon_python_lib-0.2.7a56 → sycommon_python_lib-0.2.8a1}/src/sycommon/agent/multi_agent_team.py

@@ -142,6 +142,8 @@ class TeamConfig(BaseModel):
 
     sandbox_service_name: str = "shengye-platform-sandbox"
     sandbox_timeout: int = 300
+    # 额外 middleware（应用层注入，如技能使用上报）
+    extra_middleware: list = []
     # system 技能:本地仓库目录 → 同步到沙箱 /skills/system(只读)
     system_skills_dir: Optional[str] = None
     # user 技能:标记启用沙箱 /skills/user(可写,内容由 MinIO 灌入)
@@ -685,6 +687,8 @@ async def create_multi_agent_team(
         SkillWriteGuardMiddleware(),
         SandboxPathGuardMiddleware(user_id),
     ]
+    if config.extra_middleware:
+        middleware.extend(config.extra_middleware)
     shared = config.shared_tools or [get_current_date]
 
     def _build_subagent(member: TeamMember) -> CompiledSubAgent:

{sycommon_python_lib-0.2.7a56 → sycommon_python_lib-0.2.8a1}/src/sycommon/agent/sandbox/file_ops.py

@@ -389,13 +389,15 @@ class FileOperationsMixin:
             )
             # 对齐 deepagents 0.7.1 ReadResult 分页字段：服务端按行切片后回传
             # start_line/end_line/total_lines/next_offset，框架据此渲染分页提示。
-            # no_lines_requested（limit<=0 早退）：服务端返回空 content 且无分页字段。
+            # no_lines_requested（limit<=0 早退）：服务端返回空 content + 该标志；
+            # 透传给 ReadResult，让 FilesystemMiddleware 区分「零行窗口」与「空文件」。
             return ReadResult(
                 file_data=file_data,
                 start_line=result.get("start_line"),
                 end_line=result.get("end_line"),
                 total_lines=result.get("total_lines"),
                 next_offset=result.get("next_offset"),
+                no_lines_requested=bool(result.get("no_lines_requested")),
             )
         except Exception as e:
             SYLogger.error(f"[Sandbox] 读取文件异常: {e}")
@@ -471,12 +473,14 @@ class FileOperationsMixin:
                 encoding=encoding,
             )
             # 对齐 deepagents 0.7.1 ReadResult 分页字段（与同步 read 一致）。
+            # no_lines_requested 透传：区分零行窗口与空文件（见同步版注释）。
             return ReadResult(
                 file_data=file_data,
                 start_line=result.get("start_line"),
                 end_line=result.get("end_line"),
                 total_lines=result.get("total_lines"),
                 next_offset=result.get("next_offset"),
+                no_lines_requested=bool(result.get("no_lines_requested")),
             )
         except Exception as e:
             SYLogger.error(f"[Sandbox] 异步读取文件异常: {e}")

{sycommon_python_lib-0.2.7a56 → sycommon_python_lib-0.2.8a1}/src/sycommon/agent/sandbox/http_sandbox_backend.py

@@ -60,8 +60,8 @@ class FileDownloadResult:
 from sycommon.logging.kafka_log import SYLogger
 from sycommon.agent.sandbox.file_ops import FileOperationsMixin, SANDBOX_API_PREFIX
 
+from deepagents.backends.sandbox import BaseSandbox
 from deepagents.backends.protocol import (
-    SandboxBackendProtocol,
     ExecuteResponse,
     FileDownloadResponse,
     FileUploadResponse,
@@ -219,10 +219,24 @@ def filter_instances_by_owner(instances: list, user_id: str, timeout: float = 3.
     return filtered
 
 
-class HTTPSandboxBackend(FileOperationsMixin, SandboxBackendProtocol):
+class HTTPSandboxBackend(FileOperationsMixin, BaseSandbox):
     """
     通过 HTTP API 连接远程沙箱容器
 
+    继承 BaseSandbox（而非 SandboxBackendProtocol）以解锁 deepagents
+    capture-at-source offload：execute 大输出在沙箱源端截成 head/tail 预览，
+    完整结果落盘 /large_tool_results/<tool_call_id>，模型可经 read_file 翻页恢复，
+    不必重跑命令。落盘目录由 SandboxRecoveryManager/minio_sync cleanup 兜底清理。
+    FileOperationsMixin 在 MRO 最前，read/ls/grep/edit/delete 等仍走本类自定义
+    实现（HTTP 远程调用），BaseSandbox 的 shell 默认实现不会被触发。
+    """
+
+    # capture-at-source offload：opt-in，依赖沙箱镜像含 POSIX sh + head/tail/wc/cat。
+    # 生产 Linux 沙箱走 bash heredoc 执行命令（见 _build_execute_command），必然满足。
+    enable_capture_offload = True
+
+    """
+
     支持两种模式:
     1. 直接 URL: 直接指定沙箱服务地址
     2. Nacos 服务发现: 通过服务名从 Nacos 获取实例（支持自动故障转移）

{sycommon_python_lib-0.2.7a56 → sycommon_python_lib-0.2.8a1}/src/sycommon/config/Config.py

@@ -114,6 +114,30 @@ class Config(metaclass=SingletonMeta):
                 return es
         raise ValueError(f"No configuration found for elasticsearch: {name}")
 
+    # 命名空间 → 默认租户 ID：prod/wsuat1 共享同一租户，其余环境另一租户
+    _PROD_NAMESPACES = ("prod", "wsuat1")
+    _DEFAULT_TENANT_PROD = "T000002"
+    _DEFAULT_TENANT_OTHER = "T000003"
+
+    def get_namespace_id(self, default=''):
+        """获取当前环境标识（Nacos namespaceId，如 'prod'/'wsuat1'/'dev'）。
+
+        Args:
+            default: 配置缺失时的默认值，按调用场景传入：
+                     告警展示用 '未知环境'，功能判断用 'dev'/'prod'，缓存哨兵用 None。
+        """
+        return self.config.get('Nacos', {}).get('namespaceId', default)
+
+    def get_tenant_id(self):
+        """根据当前环境推导系统默认租户 ID。
+
+        prod / wsuat1 → "T000002"，其余环境 → "T000003"。
+        仅作为系统内部消息（如 RabbitMQ SYSTEM 消息）的兜底默认值；
+        若调用方有请求上下文中的真实租户（x-tenant-header），应优先使用它。
+        """
+        ns = self.get_namespace_id()
+        return self._DEFAULT_TENANT_PROD if ns in self._PROD_NAMESPACES else self._DEFAULT_TENANT_OTHER
+
     def _process_config(self):
         # 清空列表，防止 set_attr 多次调用时重复累积
         self.llm_configs.clear()

{sycommon_python_lib-0.2.7a56 → sycommon_python_lib-0.2.8a1}/src/sycommon/database/async_base_db_service.py

@@ -29,12 +29,47 @@ def _is_retryable_tx_error(exc: Exception) -> bool:
 
 
 class AsyncBaseDBService(metaclass=SingletonMeta):
-    """数据库操作基础服务类，封装异步会话管理功能"""
+    """数据库操作基础服务类，封装异步会话管理功能
+
+    engine 不在 __init__ 时绑定，而是每次 session 时按当前 event loop 动态
+    获取（AsyncDatabaseService.engine() 按 loop 隔离）。这样子类即使作为
+    模块级单例在 import 时实例化（此时 DB 未初始化、loop 未确定），也不会
+    把 engine 绑死在错误的时机/loop 上；后台线程在独立 loop 调用时同样能
+    拿到本 loop 的连接池。
+    """
 
     def __init__(self):
-        self.engine = AsyncDatabaseService.engine()
-        self.Session = async_sessionmaker(
-            bind=self.engine,
+        # 不缓存 engine/Session，延迟到每次使用时按当前 loop 创建，
+        # 见 _session_factory()。保留 engine 只读属性兼容旧子类（见下）。
+        pass
+
+    @property
+    def engine(self):
+        """当前 loop 的 engine（兼容旧子类直接访问 self.engine 的写法）
+
+        注意：仅在调试/日志场景使用；正式会话请走 session()/execute()，
+        不要把返回的 engine 跨 loop 缓存复用。
+        """
+        return AsyncDatabaseService.engine()
+
+    @property
+    def Session(self) -> async_sessionmaker:
+        """当前 loop 的会话工厂（兼容旧子类直接访问 self.Session 的写法）
+
+        用法与旧版一致：`async with self.Session() as session: ...`
+        但每次访问都按当前 loop 重新构建，不要将其返回值跨 loop 缓存。
+        """
+        return self._session_factory()
+
+    def _session_factory(self) -> async_sessionmaker:
+        """按当前 loop 创建会话工厂（engine 由 AsyncDatabaseService 按 loop 提供）"""
+        engine = AsyncDatabaseService.engine()
+        if engine is None:
+            raise RuntimeError(
+                "数据库未初始化：AsyncDatabaseService.engine() 返回 None，"
+                "请先通过 Services.plugins(database_service=...) 完成初始化")
+        return async_sessionmaker(
+            bind=engine,
             class_=AsyncSession,
             expire_on_commit=False
         )
@@ -45,7 +80,7 @@ class AsyncBaseDBService(metaclass=SingletonMeta):
         异步数据库会话上下文管理器
         自动处理会话的创建、提交、回滚和关闭
         """
-        async with self.Session() as session:
+        async with self._session_factory()() as session:
             try:
                 yield session
                 await session.commit()
@@ -81,7 +116,7 @@ class AsyncBaseDBService(metaclass=SingletonMeta):
         last_exc = None
 
         while True:
-            async with self.Session() as session:
+            async with self._session_factory()() as session:
                 try:
                     result = await fn(session)
                     await session.commit()

{sycommon_python_lib-0.2.7a56 → sycommon_python_lib-0.2.8a1}/src/sycommon/database/async_database_service.py

@@ -1,5 +1,6 @@
 from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
 from sqlalchemy import text, event
+import asyncio
 
 from sycommon.config.Config import SingletonMeta
 from sycommon.config.DatabaseConfig import DatabaseConfig, convert_dict_keys
@@ -9,7 +10,19 @@ from sycommon.synacos.nacos_service import NacosService
 
 
 class AsyncDatabaseService(metaclass=SingletonMeta):
-    _engine = None
+    # 按 event loop 隔离的 engine 池：{loop: AsyncEngine}
+    #
+    # 为什么不是全局单 engine：aiomysql 连接的 socket stream 在首次读写时
+    # 绑定到当时的 event loop，跨 loop 复用会抛
+    # "got Future attached to a different loop"。
+    # 业务服务的后台线程（如定时刷盘）通常跑在独立 loop，必须各用各的连接。
+    #
+    # 兼容：engine() 保持无参，自动按"当前 running loop"返回对应 engine；
+    # 主 loop（setup_database 所在）返回初始化的那个，其他 loop 首次访问时
+    # 按同一份配置懒创建。单 loop 项目行为与之前完全一致。
+    _engines: dict = {}
+    _main_loop = None          # setup_database 时的 loop
+    _db_config = None          # DatabaseConfig，供其他 loop 懒建 engine
     # setup 时记录入参，供 reload() 重建使用
     _setup_args = None
 
@@ -24,8 +37,15 @@ class AsyncDatabaseService(metaclass=SingletonMeta):
             # 初始化 DatabaseConnector (传入配置)
             connector = AsyncDatabaseConnector(db_config)
 
-            # 赋值 engine
-            AsyncDatabaseService._engine = connector.engine
+            # 记录主 loop 与其 engine
+            try:
+                AsyncDatabaseService._main_loop = asyncio.get_running_loop()
+            except RuntimeError:
+                AsyncDatabaseService._main_loop = None
+            AsyncDatabaseService._db_config = db_config
+            AsyncDatabaseService._engines = {
+                AsyncDatabaseService._main_loop: connector.engine
+            }
 
             # 执行异步测试连接
             if not await connector.test_connection():
@@ -39,43 +59,90 @@ class AsyncDatabaseService(metaclass=SingletonMeta):
 
     @staticmethod
     def engine():
-        return AsyncDatabaseService._engine
+        """返回当前 running loop 对应的 engine。
+
+        主 loop 返回初始化的共享 engine；其他 loop（后台线程）首次调用时
+        按同一份数据库配置懒创建独立 engine（连接归该 loop 专用）。
+        无 running loop（纯同步上下文）时回退主 engine。
+        """
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            # 同步上下文（如 ORM 事件回调、脚本），回退主 engine
+            return AsyncDatabaseService._engines.get(
+                AsyncDatabaseService._main_loop)
+
+        if loop in AsyncDatabaseService._engines:
+            return AsyncDatabaseService._engines[loop]
+
+        # 其他 loop 首次访问：懒建专属 engine
+        if AsyncDatabaseService._db_config is None:
+            return None
+        engine = AsyncDatabaseService._build_engine()
+        AsyncDatabaseService._engines[loop] = engine
+        return engine
+
+    @staticmethod
+    def _build_engine():
+        """按当前 running loop 创建 engine（内部使用）"""
+        connector = AsyncDatabaseConnector(AsyncDatabaseService._db_config)
+        SYLogger.info(
+            f"AsyncDatabaseService 为非主 loop 创建独立 engine "
+            f"(共 {len(AsyncDatabaseService._engines) + 1} 个)")
+        return connector.engine
 
     @staticmethod
     async def dispose() -> None:
-        """释放异步引擎连接池资源"""
-        if AsyncDatabaseService._engine is not None:
+        """释放所有 engine 的连接池资源（在各 loop 内安全地尽力释放）"""
+        engines = list(AsyncDatabaseService._engines.values())
+        AsyncDatabaseService._engines = {}
+        AsyncDatabaseService._main_loop = None
+        for engine in engines:
+            if engine is None:
+                continue
             try:
-                await AsyncDatabaseService._engine.dispose()
+                # dispose 是协程但内部只做连接关闭，跨 loop 调用对
+                # 空闲连接安全；忙碌连接的 loop 此时应已停止
+                await engine.dispose()
             except Exception as e:
                 SYLogger.error(f"AsyncDatabase engine dispose error: {e}")
-            finally:
-                AsyncDatabaseService._engine = None
 
     @classmethod
     async def reload(cls) -> None:
         """配置热更新：dispose 旧引擎并按最新配置重建，失败回退。"""
         if not cls._setup_args:
             return
-        old_engine = cls._engine
-        # 清掉 AsyncDatabaseConnector 单例缓存，使其按新配置重建
-        from sycommon.config.Config import SingletonMeta
-        SingletonMeta._instances.pop(AsyncDatabaseConnector, None)
+        old_engines = dict(cls._engines)
+        old_main_loop = cls._main_loop
         try:
             await cls.setup_database(*cls._setup_args)
         except Exception as e:
             SYLogger.error(f"AsyncDatabaseService reload 重建失败: {e}", exc_info=True)
-            cls._engine = old_engine
+            cls._engines = old_engines
+            cls._main_loop = old_main_loop
             return
-        # 新 engine 建好，释放旧的
-        if old_engine is not None:
+        # 新 engine 建好，释放旧的（含其他 loop 的，其连接已失效，
+        # 下次访问会按新 _db_config 自动重建）
+        for loop, old_engine in old_engines.items():
+            if old_engine is None:
+                continue
             try:
                 await old_engine.dispose()
             except Exception as e:
                 SYLogger.error(f"AsyncDatabaseService reload 释放旧 engine 失败: {e}")
 
 
-class AsyncDatabaseConnector(metaclass=SingletonMeta):
+class AsyncDatabaseConnector:
+    """数据库连接器（每次实例化都新建 engine）
+
+    不能用 SingletonMeta：AsyncDatabaseService 按 event loop 隔离 engine，
+    需要为每个 loop 各建一个连接池；单例会让所有 loop 拿到同一个 engine，
+    跨 loop 使用必抛 "attached to a different loop"。
+
+    注意：reload() 原本靠 `SingletonMeta._instances.pop(AsyncDatabaseConnector)`
+    清缓存强制重建——去掉单例后每次实例化本身就是全新 engine，无需再清。
+    """
+
     def __init__(self, db_config: DatabaseConfig):
         # 从 DatabaseConfig 中提取数据库连接信息
         self.db_user = db_config.username

{sycommon_python_lib-0.2.7a56 → sycommon_python_lib-0.2.8a1}/src/sycommon/llm/sy_langfuse.py

@@ -48,7 +48,7 @@ class LangfuseInitializer(metaclass=SingletonMeta):
 
             server_name = config_dict.get('Name', '')
             langfuse_configs = config_dict.get('LangfuseConfig', [])
-            environment = config_dict.get('Nacos', {}).get('namespaceId', '')
+            environment = Config().get_namespace_id('')
 
             # 3. 查找匹配的配置项
             target_config = next(

{sycommon_python_lib-0.2.7a56 → sycommon_python_lib-0.2.8a1}/src/sycommon/llm/token_usage_mysql_service.py

@@ -134,7 +134,7 @@ class TokenUsageMySQLService(metaclass=SingletonMeta):
                         f"TokenUsageMySQLService 加载 service_name: {cls._service_name}")
 
             if cls._system_env is None:
-                env = config.get('Nacos', {}).get('namespaceId', None)
+                env = Config().get_namespace_id(None)
                 if env:
                     cls._system_env = env
                     logging.info(

{sycommon_python_lib-0.2.7a56 → sycommon_python_lib-0.2.8a1}/src/sycommon/logging/kafka_log.py

@@ -236,7 +236,7 @@ class KafkaSink:
                 "tenantId": "",
                 "userId": "",
                 "customerId": "",
-                "env": Config().config.get('Nacos', {}).get('namespaceId', ''),
+                "env": Config().get_namespace_id(''),
                 "priReqSource": "",
                 "reqSource": "",
                 "serviceId": self.service_id,

{sycommon_python_lib-0.2.7a56 → sycommon_python_lib-0.2.8a1}/src/sycommon/middleware/sandbox.py

@@ -340,6 +340,10 @@ _GREP_TIMEOUT = 60
 # read 文本路径服务端字节上限（对齐 deepagents _READ_COMMAND_TEMPLATE 的
 # MAX_OUTPUT_BYTES=500KiB）：超大文本文件不会把整包塞进 HTTP 响应/内存。
 _READ_MAX_OUTPUT_BYTES = 500 * 1024
+# read 提前停止后补数 total_lines 的文件大小闸门（对齐 deepagents sandbox.py:499
+# MAX_LINE_COUNT_BYTES=1MiB）：超过此大小的文件不数总行数（total_lines=None），
+# 避免 GB 级文件的逐行计数把 read 拖成慢操作。
+_READ_TOTAL_LINE_MAX_BYTES = 1024 * 1024
 # 默认工作目录配置
 # - Linux: /data/sycommon_sandbox (固定路径，自动创建)
 # - macOS/Windows: 使用系统临时目录
@@ -1027,8 +1031,10 @@ def setup_sandbox_handler(app: FastAPI, config: dict = None):
 
                 # limit<=0：协议 no_lines_requested —— 不读文件，返回空内容 + 标志位，
                 # 不带任何分页字段（客户端填 ReadResult.no_lines_requested=True）。
+                # 对齐 deepagents _build_read_cmd 的 limit<=0 早退分支。区别于空文件
+                # （空文件走上面的 "File exists but has empty contents" 提示）。
                 if limit is not None and limit <= 0:
-                    return ReadResponse(content="", error=None, encoding="utf-8")
+                    return ReadResponse(content="", error=None, encoding="utf-8", no_lines_requested=True)
 
                 lines = []
                 lines_read = 0
@@ -1082,12 +1088,18 @@ def setup_sandbox_handler(app: FastAPI, config: dict = None):
                     next_offset = None
                 else:
                     # 提前停止（limit 到顶 / 字节截断）：需要 total_lines 才能算「剩余」。
-                    # 大文件全量计数代价高，这里只在截断时补一次剩余行数扫描
-                    # （对齐 deepagents「total_lines 已知时才报」的做法）。
-                    try:
-                        with open(file_path, 'r', encoding='utf-8', newline=None) as f:
-                            total_lines = sum(1 for _ in f)
-                    except OSError:
+                    # 大文件全量计数代价高——先比 st_size 与 _READ_TOTAL_LINE_MAX_BYTES
+                    # （对齐 deepagents sandbox.py:499 的 MAX_LINE_COUNT_BYTES=1MiB 闸门），
+                    # 超过则不数（返回 None，next_offset 退化为 end_line），避免无界扫描
+                    # 把 read 变成对 GB 级文件的逐行计数慢操作。
+                    file_size = os.path.getsize(file_path)
+                    if file_size <= _READ_TOTAL_LINE_MAX_BYTES:
+                        try:
+                            with open(file_path, 'r', encoding='utf-8', newline=None) as f:
+                                total_lines = sum(1 for _ in f)
+                        except OSError:
+                            total_lines = None
+                    else:
                         total_lines = None
                     # next_offset = end_line（0-indexed 下一行 = 1-indexed 末行号），
                     # 仅当确实还有后续行时设置；否则视为读到末尾。
@@ -1724,19 +1736,65 @@ def setup_sandbox_handler(app: FastAPI, config: dict = None):
         grep_opts = "-rHnFZ" if use_null_separator else "-rHnF"
 
         # 安全处理 glob_pattern，使用 shlex.quote 防止命令注入
-        glob_pattern = f"--include={shlex.quote(req.glob)}" if req.glob else ""
         pattern_escaped = shlex.quote(req.pattern)
 
-        # 注意：不再用 2>/dev/null || true，以便捕获 stderr 用于错误诊断
-        cmd = f"grep {grep_opts} {glob_pattern} -e {pattern_escaped} {quoted_path}"
+        # glob 含 '/'（如 src/**/*.py）时，GNU grep --include 只匹配 basename，
+        # 会静默返回 0 条（对齐 deepagents sandbox.py:684 _build_grep_cmd 的判定）。
+        # 这种路径 glob 改走 Python glob 预筛文件清单 + grep -F 逐文件/批量，
+        # 避免「带路径 glob 搜不到东西」的隐蔽 bug。
+        path_glob = req.glob
+        use_path_glob = bool(path_glob and "/" in path_glob)
+        if not use_path_glob:
+            glob_pattern = f"--include={shlex.quote(req.glob)}" if req.glob else ""
+            # 注意：不再用 2>/dev/null || true，以便捕获 stderr 用于错误诊断
+            cmd = f"grep {grep_opts} {glob_pattern} -e {pattern_escaped} {quoted_path}"
+        else:
+            glob_pattern = ""  # 不用 --include；文件清单由 Python glob 预筛后喂给 grep
+
         # 对齐 deepagents 0.7.1 max_count：服务端用 head 早停，多取 1 条用于判断是否截断。
         # （grep -r 没有真正的全局计数上限，head -n N+1 截 stdout 后，客户端按 N 裁剪、
         #  超过即 truncated=True。与 deepagents BaseSandbox._build_grep_cmd 同款思路。）
         max_count = req.max_count
-        if max_count is not None and max_count >= 0:
+        if not use_path_glob and max_count is not None and max_count >= 0:
             # || true 兜底 SIGPIPE（head 读够后关闭管道，grep 收到 SIGPIPE 退出码非 0）
             cmd = f"{cmd} | head -n {int(max_count) + 1} || true"
 
+        # 含路径 glob 的分支：Python glob 预筛出匹配文件清单（仅文件，递归），
+        # 经 xargs 批量喂给 grep -F。沿用 -Z/-Hn 与正文相同的 NUL/冒号解析，故
+        # 下游 _parse_grep_results 无需改动。文件清单为空时直接返回 0 条，避免起
+        # `grep -e pat`（无文件参数）误把 stdin 当搜索源。
+        def _resolve_path_glob_files():
+            import glob as glob_module
+            full_pattern = os.path.join(search_path, path_glob)
+            try:
+                files = sorted(glob_module.glob(full_pattern, recursive=True))
+            except (FileNotFoundError, NotADirectoryError, PermissionError) as e:
+                SYLogger.warning(f"[Sandbox Server] grep 路径 glob 异常: {e}")
+                return []
+            workspace_resolved_g = os.path.realpath(workspace)
+            safe = []
+            for m in files:
+                if os.path.isdir(m):
+                    continue  # grep 按文件搜，目录跳过
+                try:
+                    if not _is_path_within(m, workspace_resolved_g):
+                        continue
+                except OSError:
+                    continue
+                safe.append(m)
+            return safe
+
+        if use_path_glob:
+            path_glob_files = await asyncio.to_thread(_resolve_path_glob_files)
+            if not path_glob_files:
+                return GrepResponse(matches=[])
+            # xargs -0：文件名以 NUL 分隔喂入，文件名含空格/引号/换行也安全。
+            # find ... -print0 | grep -FZne pattern --files-from=... 也行，但 xargs 最 portable。
+            files_argv = " ".join(shlex.quote(f) for f in path_glob_files)
+            # 不加 -r（已显式给文件清单，无需递归）；保留 -H(始终带文件名) -n(行号) -F(字面量) -Z(NUL)。
+            path_glob_grep_opts = "-HnFZ" if use_null_separator else "-HnF"
+            cmd = f"printf '%s\\0' {files_argv} | xargs -0 grep {path_glob_grep_opts} -e {pattern_escaped}"
+
         # 使用 asyncio.create_subprocess_shell 异步执行
         proc = await asyncio.create_subprocess_shell(
             cmd,
@@ -1831,6 +1889,7 @@ def setup_sandbox_handler(app: FastAPI, config: dict = None):
 
         matches = await asyncio.to_thread(_parse_grep_results)
         # 对齐 deepagents 0.7.1：超出 max_count 即置 truncated（多取的 1 条在这里裁掉）。
+        # 路径 glob 分支没在服务端 head 早停（直接 grep 文件清单），这里统一兜底裁剪。
         truncated = False
         if max_count is not None and len(matches) > max_count:
             matches = matches[:max_count]

{sycommon_python_lib-0.2.7a56 → sycommon_python_lib-0.2.8a1}/src/sycommon/models/base_http.py

@@ -99,3 +99,55 @@ def error_content(
 ) -> dict:
     """构建错误响应内容字典，支持自定义错误码"""
     return build_response_content(data=data, code=code, message=message)
+
+
+# =====================================================================
+# HTTP 语义响应（新方式，推荐使用）
+#
+# 与上面 0/1 业务码的区别：code 直接用 HTTP 状态码语义——
+#   成功 code=200 / 失败 code=500，HTTP status 同步对应（200 / 500），
+# success 由 code 是否为 2xx 推导。不再用 0/1 代表成功失败。
+# 旧函数保留兼容，新项目请用 ok() / fail()。
+# =====================================================================
+
+
+def http_response(
+    data: T | Any = None,
+    code: int = status.HTTP_200_OK,
+    message: str = None,
+) -> JSONResponse:
+    """按 HTTP 状态码语义构建响应，code 即业务码也是 HTTP status。
+
+    success 自动按 code 是否为 2xx 推导。
+    """
+    content = BaseResponseModel(
+        code=code,
+        message=message,
+        success=200 <= code < 300,
+        data=data,
+    )
+    if isinstance(content.data, BaseModel):
+        body = {
+            "code": content.code,
+            "message": content.message,
+            "success": content.success,
+            "data": content.data.model_dump(),
+        }
+    else:
+        body = content.model_dump()
+    return JSONResponse(content=body, status_code=code)
+
+
+def ok(data: T | Any = None, message: str = None) -> JSONResponse:
+    """成功响应：code=200, success=true, HTTP 200"""
+    return http_response(data=data, code=status.HTTP_200_OK, message=message)
+
+
+def fail(
+    message: str = None,
+    data: T | Any = None,
+    code: int = status.HTTP_500_INTERNAL_SERVER_ERROR,
+) -> JSONResponse:
+    """失败响应：默认 code=500, success=false, HTTP 500（可用 code 覆盖）"""
+    return http_response(data=data, code=code, message=message)
+

{sycommon_python_lib-0.2.7a56 → sycommon_python_lib-0.2.8a1}/src/sycommon/models/sandbox.py

@@ -143,6 +143,11 @@ class ReadResponse(BaseModel):
     end_line: Optional[int] = None
     total_lines: Optional[int] = None
     next_offset: Optional[int] = None
+    # limit<=0 早退标志（对齐 deepagents ReadResult.no_lines_requested）：
+    # True 表示「文件未检视、零行窗口」，与「空文件」区分开。客户端据此
+    # 填 ReadResult.no_lines_requested，让 FilesystemMiddleware 给出与框架
+    # 合成实现一致的分页提示（NO_LINES_REQUESTED_WARNING）而非空文件提示。
+    no_lines_requested: bool = False
 
 
 class WriteRequest(BaseModel):