sycommon-python-lib 0.2.2a3__py3-none-any.whl → 0.2.2a5__py3-none-any.whl

command/cli.py

@@ -49,6 +49,12 @@ def create_init_parser(subparsers) -> None:
   web   - 标准 FastAPI Web 服务，适合 RESTful API 开发
   agent - AI Agent 服务，基于 langgraph 实现状态图
 
+CLI 项目结构:
+  commands/         - 子命令目录
+  model/            - 数据模型
+  client/           - 外部服务客户端
+  app.py            - CLI 入口 (argparse)
+
 Agent 项目结构:
   agent/           - Agent 核心 (main_agent, nodes, states, enums)
   api/sse/         - SSE 流式接口
@@ -79,7 +85,7 @@ Web 项目结构:
     # 位置参数
     init_parser.add_argument(
         "project_type",
-        choices=["web", "agent"],
+        choices=["web", "agent", "cli"],
         help="项目类型：web / agent"
     )
     init_parser.add_argument(
@@ -221,6 +227,8 @@ def _detect_project_type(project_path) -> str | None:
     if (project_path / "agent" / "main_agent.py").exists() or \
        (project_path / "agent" / "enums").is_dir():
         return "agent"
+    if (project_path / "commands").is_dir() and (project_path / "app.py").exists():
+        return "cli"
     if (project_path / "api").is_dir():
         return "web"
     return None
@@ -247,13 +255,19 @@ def handle_doctor_command(args) -> bool:
         warnings.append("无法识别项目类型 (非 web / agent 标准结构)")
 
     # 1. 检查必要文件
-    required_files = ["app.py", "requirements.txt"]
+    if project_type == "cli":
+        required_files = ["app.py", "pyproject.toml"]
+    else:
+        required_files = ["app.py", "requirements.txt"]
     for file in required_files:
         if not (project_path / file).exists():
             issues.append(f"缺少必要文件: {file}")
 
     # 2. 检查配置文件
-    config_files = ["app.yaml", ".env"]
+    if project_type == "cli":
+        config_files = [".env"]
+    else:
+        config_files = ["app.yaml", ".env"]
     for file in config_files:
         if not (project_path / file).exists():
             warnings.append(f"缺少配置文件: {file}")
@@ -276,6 +290,8 @@ def handle_doctor_command(args) -> bool:
                 issues.append(f"缺少 Agent 核心文件: {file}")
     elif project_type == "web":
         required_dirs = ["api", "model", "tools", "client"]
+    elif project_type == "cli":
+        required_dirs = ["commands", "model", "tools"]
     else:
         required_dirs = ["api", "model", "tools"]
 
@@ -351,6 +367,11 @@ def handle_list_command(args) -> bool:
                      "api/sse/", "api/query.py", "tools/", "model/", "db/"],
             "features": "nacos, kafka_log, llm, sentry (默认启用)",
         },
+        "cli": {
+            "desc": "Python CLI 命令行工具 (argparse)",
+            "dirs": ["commands/", "model/", "client/"],
+            "features": "无默认依赖 (精简模板)",
+        },
     }
 
     for name, info in templates.items():

command/core/models.py

@@ -13,6 +13,19 @@ AGENT_DEFAULTS = {
     "llm": True,
 }
 
+# CLI 项目默认关闭所有服务依赖
+CLI_DEFAULTS = {
+    "database": False,
+    "rabbitmq": False,
+    "nacos": False,
+    "kafka_log": False,
+    "sse": False,
+    "llm": False,
+    "redis": False,
+    "elasticsearch": False,
+    "sentry": False,
+}
+
 
 @dataclass
 class FeatureOptions:
@@ -32,6 +45,8 @@ class FeatureOptions:
         """根据项目类型返回推荐默认配置"""
         if project_type == "agent":
             return cls(**AGENT_DEFAULTS)
+        if project_type == "cli":
+            return cls(**CLI_DEFAULTS)
         return cls()
 
     def to_template_vars(self) -> dict:

command/core/project.py

@@ -153,13 +153,19 @@ def init_project(
             'db/', 'db/service.py', 'db/model/', 'db/model/entity.py',
         ],
     }
+    # CLI 项目不需要的服务端文件
+    cli_skip_files = {'app.yaml', 'app.yaml.tpl', 'requirements.txt', 'requirements.txt.tpl', 'Dockerfile', 'Dockerfile.tpl'}
     disabled_features = {
         key for key, flag_val in features.to_template_vars().items()
         if flag_val == 'false' and key in feature_map
     }
 
     def _should_skip(rel_path: str) -> bool:
-        """检查文件是否因功能关闭而应跳过"""
+        """检查文件是否因功能关闭或项目类型而应跳过"""
+        # CLI 项目跳过不需要的服务端文件
+        if project_type == "cli":
+            if rel_path in cli_skip_files or rel_path.replace('.tpl', '') in cli_skip_files:
+                return True
         for feat_key in disabled_features:
             for pattern in feature_map[feat_key]:
                 if pattern in rel_path:
@@ -191,7 +197,7 @@ def init_project(
     copied_files = _render_files(file_mappings, context, project_path, verbose)
 
     if copied_files > 0:
-        _print_success_message(project_path, project_name, copied_files)
+        _print_success_message(project_path, project_name, copied_files, project_type)
         return True
     else:
         print_warning("未创建任何文件，可能是缺少模板文件或模板路径配置错误")
@@ -284,7 +290,8 @@ def _render_files(
 def _print_success_message(
     project_path: Path,
     project_name: str,
-    copied_files: int
+    copied_files: int,
+    project_type: str = "web",
 ) -> None:
     """打印成功信息"""
     print_success(f"模板工程 {project_name} 创建完成！")
@@ -293,7 +300,11 @@ def _print_success_message(
     print()
     print_info("下一步操作:")
     print(f"  cd {project_name}")
-    print(f"  # 建议先创建虚拟环境")
-    print(f"  python -m venv .venv && source .venv/bin/activate")
-    print(f"  pip install -r requirements.txt")
-    print(f"  python app.py")
+    if project_type == "cli":
+        print(f"  uv sync")
+        print(f"  uv run python app.py")
+    else:
+        print(f"  # 建议先创建虚拟环境")
+        print(f"  python -m venv .venv && source .venv/bin/activate")
+        print(f"  pip install -r requirements.txt")
+        print(f"  python app.py")

command/templates/cli/README.md.tpl

@@ -0,0 +1,54 @@
+# {{ project_name }}
+
+{{ project_name }} - Python CLI 命令行工具
+
+## 项目结构
+
+```
+{{ project_name }}/
+├── commands/             # 子命令目录
+│   ├── __init__.py
+│   └── hello.py          # 示例子命令
+├── tools/                # 工具函数
+├── model/                # 数据模型
+├── client/               # 外部服务客户端
+├── app.py                # CLI 入口
+├── pyproject.toml        # uv 项目配置
+└── README.md
+```
+
+## 快速开始
+
+### 安装依赖
+```bash
+uv sync
+```
+
+### 使用
+```bash
+# 查看帮助
+uv run python app.py -h
+
+# hello 命令
+uv run python app.py hello --name "World"
+
+# 查看版本
+uv run python app.py version
+```
+
+### 添加新子命令
+
+1. 在 `commands/` 目录下创建新模块，例如 `commands/xxx.py`
+2. 实现 `handle_xxx(args)` 函数
+3. 在 `app.py` 中注册子命令：
+
+```python
+from commands.xxx import handle_xxx
+
+# 在 create_parser() 中添加：
+xxx_parser = subparsers.add_parser("xxx", help="xxx 说明")
+
+# 在 main() 中添加：
+elif args.command == "xxx":
+    handle_xxx(args)
+```

command/templates/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI 项目模板"""

command/templates/cli/app.py.tpl

@@ -0,0 +1,45 @@
+"""
+{{ project_name }} - CLI 工具入口
+创建时间: {{ create_time }}
+作者: {{ author }}
+"""
+import argparse
+import sys
+
+from commands.hello import handle_hello
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """创建命令行解析器"""
+    parser = argparse.ArgumentParser(
+        prog="{{ project_name }}",
+        description="{{ project_name }} - CLI 命令行工具",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="子命令")
+
+    # hello 子命令
+    hello_parser = subparsers.add_parser("hello", help="打招呼")
+    hello_parser.add_argument("--name", default="World", help="名字")
+
+    # version 子命令
+    subparsers.add_parser("version", help="显示版本")
+
+    return parser
+
+
+def main() -> None:
+    """CLI 主入口"""
+    parser = create_parser()
+    args = parser.parse_args()
+
+    if args.command == "hello":
+        handle_hello(args)
+    elif args.command == "version":
+        print("{{ project_name }} 1.0.0")
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

command/templates/cli/commands/__init__.py.tpl

@@ -0,0 +1 @@
+"""子命令模块"""

command/templates/cli/commands/hello.py.tpl

@@ -0,0 +1,6 @@
+"""hello 子命令"""
+
+
+def handle_hello(args) -> None:
+    """处理 hello 命令"""
+    print(f"Hello, {args.name}!")

command/templates/cli/pyproject.toml.tpl

@@ -0,0 +1,14 @@
+[project]
+name = "{{ project_name }}"
+version = "0.1.0"
+description = "{{ project_name }} - CLI 命令行工具"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.scripts]
+{{ short_project_name }} = "app:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

command/templates/cli/tools/__init__.py.tpl

@@ -0,0 +1,3 @@
+"""
+工具函数模块
+"""

sycommon/agent/sandbox/file_ops.py

@@ -149,11 +149,11 @@ class FileOperationsMixin:
     def _check_workspace_exists_sync(self: "HTTPSandboxBackend") -> bool:
         """检查沙箱工作空间是否存在（同步版本）"""
         try:
-            self._post_sync(f"{SANDBOX_API_PREFIX}/ls", {
+            result = self._post_sync(f"{SANDBOX_API_PREFIX}/stat", {
                 "path": "/",
                 "user_id": self.user_id
             })
-            return True
+            return result.get("exists", False)
         except Exception as e:
             SYLogger.warning(f"[Sandbox] 检查工作空间失败: {e}")
             return False
@@ -161,11 +161,11 @@ class FileOperationsMixin:
     async def _check_workspace_exists_async(self: "HTTPSandboxBackend") -> bool:
         """检查沙箱工作空间是否存在（异步版本）"""
         try:
-            await self._post_async_with_failover(f"{SANDBOX_API_PREFIX}/ls", {
+            result = await self._post_async_with_failover(f"{SANDBOX_API_PREFIX}/stat", {
                 "path": "/",
                 "user_id": self.user_id
             })
-            return True
+            return result.get("exists", False)
         except Exception as e:
             SYLogger.warning(f"[Sandbox] 检查工作空间失败: {e}")
             return False
@@ -184,47 +184,31 @@ class FileOperationsMixin:
         """列出目录内容"""
         try:
             self._ensure_synced_sync()
-            print(
-                f"[Sandbox-DEBUG] ls() called with path={repr(path)}, user_id={repr(self.user_id)}", flush=True)
             SYLogger.info(f"[Sandbox] 列出目录: {path}")
             result = self._post_sync(f"{SANDBOX_API_PREFIX}/ls", {
                 "path": path,
                 "user_id": self.user_id
             })
-            print(
-                f"[Sandbox-DEBUG] ls() raw result type={type(result).__name__}, repr={repr(result)[:500]}", flush=True)
             entries = [FileInfo(**item) for item in result]
-            print(
-                f"[Sandbox-DEBUG] ls() parsed entries={len(entries)}", flush=True)
             SYLogger.info(f"[Sandbox] 目录内容: {len(entries)} 项")
             return LsResult(entries=entries)
         except Exception as e:
-            print(
-                f"[Sandbox-DEBUG] ls() EXCEPTION: {type(e).__name__}: {e}", flush=True)
             SYLogger.error(f"[Sandbox] 列出目录失败: {e}")
             return LsResult(error=str(e))
 
     async def als(self: "HTTPSandboxBackend", path: str) -> LsResult:
-        """异步列出目录内容（真正的异步实现）"""
+        """异步列出目录内容"""
         try:
             await self._ensure_synced_async()
-            print(
-                f"[Sandbox-DEBUG] als() called with path={repr(path)}, user_id={repr(self.user_id)}, base_url={repr(self._base_url if hasattr(self, '_base_url') else 'N/A')}", flush=True)
             SYLogger.info(f"[Sandbox] 异步列出目录: {path}")
             result = await self._post_async_with_failover(f"{SANDBOX_API_PREFIX}/ls", {
                 "path": path,
                 "user_id": self.user_id
             })
-            print(
-                f"[Sandbox-DEBUG] als() raw result type={type(result).__name__}, repr={repr(result)[:500]}", flush=True)
             entries = [FileInfo(**item) for item in result]
-            print(
-                f"[Sandbox-DEBUG] als() parsed entries={len(entries)}, first 3 paths={[e.get('path','?') if isinstance(e, dict) else getattr(e, 'path','?') for e in entries[:3]]}", flush=True)
             SYLogger.info(f"[Sandbox] 目录内容: {len(entries)} 项")
             return LsResult(entries=entries)
         except Exception as e:
-            print(
-                f"[Sandbox-DEBUG] als() EXCEPTION: {type(e).__name__}: {e}", flush=True)
             SYLogger.error(f"[Sandbox] 异步列出目录失败: {e}")
             return LsResult(error=str(e))
 
@@ -251,15 +235,11 @@ class FileOperationsMixin:
                 SYLogger.error(f"[Sandbox] 读取文件失败: {result['error']}")
                 return ReadResult(error=result["error"])
             content = result.get("content", "")
-            SYLogger.info(f"[Sandbox] 读取完成: {len(content)} 字符")
-            # 构建 FileData 格式
-            from datetime import datetime
-            now = datetime.now().isoformat()
+            encoding = result.get("encoding", "utf-8")
+            SYLogger.info(f"[Sandbox] 读取完成: {len(content)} 字符, encoding={encoding}")
             file_data = FileData(
                 content=content,
-                encoding="utf-8",
-                created_at=result.get("created_at", now),
-                modified_at=result.get("modified_at", now),
+                encoding=encoding,
             )
             return ReadResult(file_data=file_data)
         except Exception as e:
@@ -287,14 +267,11 @@ class FileOperationsMixin:
                 SYLogger.error(f"[Sandbox] 异步读取文件失败: {result['error']}")
                 return ReadResult(error=result["error"])
             content = result.get("content", "")
-            SYLogger.info(f"[Sandbox] 异步读取完成: {len(content)} 字符")
-            from datetime import datetime
-            now = datetime.now().isoformat()
+            encoding = result.get("encoding", "utf-8")
+            SYLogger.info(f"[Sandbox] 异步读取完成: {len(content)} 字符, encoding={encoding}")
             file_data = FileData(
                 content=content,
-                encoding="utf-8",
-                created_at=result.get("created_at", now),
-                modified_at=result.get("modified_at", now),
+                encoding=encoding,
             )
             return ReadResult(file_data=file_data)
         except Exception as e:
@@ -602,29 +579,23 @@ class FileOperationsMixin:
     # ============== 文件存在检查 ==============
 
     async def astat(self: "HTTPSandboxBackend", path: str) -> "StatResult":
-        """异步检查文件或目录是否存在（尝试 read 一行来判断）"""
+        """异步检查文件或目录状态（使用 /stat 端点）"""
         try:
             await self._ensure_synced_async()
-            SYLogger.info(f"[Sandbox] 异步检查文件存在: {path}")
-
-            result = await self._post_async_with_failover(f"{SANDBOX_API_PREFIX}/read", {
-                "file_path": path,
-                "user_id": self.user_id,
-                "offset": 0,
-                "limit": 1,
+            SYLogger.info(f"[Sandbox] 异步查询文件状态: {path}")
+            result = await self._post_async_with_failover(f"{SANDBOX_API_PREFIX}/stat", {
+                "path": path,
+                "user_id": self.user_id
             })
-            # read 成功返回结果说明文件存在
-            if result and not result.get("error"):
-                return StatResult(path=path, exists=True, is_dir=False, size=0)
-
-            error = result.get("error", "") if result else ""
-            # 如果错误是 is a directory，说明是目录，也存在
-            if "is a directory" in error.lower() or "is_dir" in error.lower():
-                return StatResult(path=path, exists=True, is_dir=True, size=0)
-
-            return StatResult(path=path, exists=False)
+            return StatResult(
+                path=result.get("path", path),
+                exists=result.get("exists", False),
+                is_dir=result.get("is_dir", False),
+                size=result.get("size", 0),
+                error=result.get("error")
+            )
         except Exception as e:
-            SYLogger.error(f"[Sandbox] 异步检查文件存在异常: {e}")
+            SYLogger.error(f"[Sandbox] 异步查询文件状态异常: {e}")
             return StatResult(path=path, error=str(e))