sycommon-python-lib 0.2.1b9__py3-none-any.whl → 0.2.2__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 @@
+"""
+工具函数模块
+"""

nexus/__init__.py

@@ -0,0 +1,40 @@
+import subprocess
+import sys
+import os
+import glob
+import argparse
+
+
+NEXUS_URL = "http://192.168.2.174:8081"
+USERNAME = "Osulcode.xiao"
+PASSWORD = "Osulcode.xiao@123"
+REPOSITORY = "shengye"
+
+
+def main():
+    parser = argparse.ArgumentParser(prog="sypublish", description="上传 whl 到 Nexus")
+    parser.add_argument("file", nargs="?", help="whl 文件路径 (默认: dist/*.whl 中最新的)")
+    parser.add_argument("--url", default=NEXUS_URL, help=f"Nexus 地址 (默认: {NEXUS_URL})")
+    parser.add_argument("-r", "--repository", default=REPOSITORY, help=f"仓库名称 (默认: {REPOSITORY})")
+    args = parser.parse_args()
+
+    if args.file:
+        file_path = args.file
+    else:
+        dist_files = sorted(glob.glob("dist/*.whl"))
+        if not dist_files:
+            print("No .whl file found in dist/")
+            sys.exit(1)
+        file_path = dist_files[-1]
+
+    if not os.path.exists(file_path):
+        print(f"File not found: {file_path}")
+        sys.exit(1)
+
+    repo_url = f"{args.url}/repository/{args.repository}/"
+    cmd = ["twine", "upload", "--repository-url", repo_url, file_path, "-u", USERNAME, "-p", PASSWORD]
+    sys.exit(subprocess.call(cmd))
+
+
+if __name__ == "__main__":
+    main()

sycli/agents/prompts.py

@@ -379,3 +379,91 @@ SERVICE_REPORT:
   notes: {any relevant notes about the service state}
 ```
 """
+
+# ── Direction Correction (E2) ────────────────────────────────────
+
+DIRECTION_CORRECTION_PROMPT = """\
+你是一个架构纠偏专家。RL 优化 agent 已经在错误方向上持续了多轮。
+
+## 失败轨迹
+{failure_trajectory}
+
+## 当前架构信息
+- 框架: {framework}
+- 架构模式: {architecture_pattern}
+- 启动方式: {startup_method}
+- 关键模块: {key_modules}
+
+## 分析要求
+1. 指出当前方向的**根本问题**（不是表面症状）
+2. 分析为什么 LLM 一直在错误方向上尝试（可能的认知偏差）
+3. 建议一个**完全不同**的架构/实现方向
+4. 列出需要**避免**的策略类型
+5. 列出**应该尝试**的策略类型
+
+## 输出格式（严格遵守）
+
+CORRECTION_ANALYSIS:
+  root_cause: |
+    （根本原因分析）
+  wrong_directions:
+    - （错误方向1）
+    - （错误方向2）
+  suggested_direction: |
+    （建议的新方向）
+  constraints:
+    - （必须遵守的约束1）
+    - （必须遵守的约束2）
+  avoid_strategies:
+    - （应避免的策略类型1）
+    - （应避免的策略类型2）
+  recommended_strategies:
+    - name: （策略名称）
+      approach: （具体方法）
+      focus: （聚焦领域）
+"""
+
+# ── Pre-Analysis (E5) ────────────────────────────────────────────
+
+PRE_ANALYSIS_PROMPT = """\
+你是一个项目分析专家。在开始 RL 优化前，请对项目进行深度预分析。
+
+## 项目环境信息
+{environment_info}
+
+## 预分析目标
+1. **启动方式分析**: 项目如何启动？有哪些可选的启动方式？
+2. **架构模式识别**: 项目采用了什么架构模式？各模块职责是什么？
+3. **方案优劣评估**: 当前架构方案的优势和不足是什么？
+4. **风险识别**: 优化过程中可能遇到的主要风险
+5. **优化建议**: 建议的优化方向和优先级
+
+## 输出格式（严格遵守）
+
+PRE_ANALYSIS:
+  startup_analysis:
+    primary_method: （主要启动方式）
+    alternative_methods: （其他可选方式）
+    configuration: （关键配置）
+  architecture_analysis:
+    pattern: （架构模式名称）
+    description: （模式描述）
+    modules:
+      - name: （模块名）
+        role: （职责描述）
+        dependencies: （依赖的其他模块）
+    data_flow: （数据流向描述）
+  strengths:
+    - （优势1）
+    - （优势2）
+  weaknesses:
+    - （不足1）
+    - （不足2）
+  risks:
+    - risk: （风险描述）
+      mitigation: （缓解措施）
+  optimization_priorities:
+    - priority: HIGH|MEDIUM|LOW
+      area: （优化领域）
+      reason: （原因）
+"""

sycli/commands/resume_cmd.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import asyncio
 import json
+import subprocess
 from pathlib import Path
 
 from sycli.core.backend import create_backend
@@ -14,6 +15,99 @@ from sycli.mode.create import run_create
 from sycli.mode.optimize import run_optimize
 
 
+def _show_resume_summary(sycli_dir: Path, state: dict) -> None:
+    """显示恢复前的进展摘要。"""
+    # 尝试从 optimization_log.jsonl 读取最近事件
+    log_file = sycli_dir / "optimization_log.jsonl"
+    if log_file.exists():
+        try:
+            recent_events: list[dict] = []
+            with open(log_file, encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if line:
+                        recent_events.append(json.loads(line))
+            # 只保留 round_end 事件
+            round_ends = [e for e in recent_events if e.get("event") == "round_end"]
+            if round_ends:
+                info("最近轮次:")
+                for ev in round_ends[-5:]:
+                    data = ev.get("data", {})
+                    r = ev.get("round", "?")
+                    score = data.get("score", 0)
+                    decision = data.get("decision", "?")
+                    strategy = data.get("strategy", "")
+                    info(f"  R{r}: score={score:.3f}, decision={decision}, strategy={strategy}")
+        except Exception:
+            pass
+
+    # 从 rounds.json 读取最佳得分
+    rounds_file = sycli_dir / "rl" / "rounds.json"
+    if rounds_file.exists():
+        try:
+            with open(rounds_file) as f:
+                rounds = json.load(f)
+            if rounds:
+                best = max(rounds, key=lambda r: r.get("score", 0))
+                info(f"最佳轮次: R{best.get('round_number', '?')}, score={best.get('score', 0):.3f}")
+                total_rounds = len(rounds)
+                info(f"已完成轮次: {total_rounds}")
+        except Exception:
+            pass
+
+
+def _verify_git_state(project_root: Path, state: dict) -> tuple[bool, str]:
+    """验证 git 状态与记录一致。
+
+    Returns:
+        (is_consistent, message)
+    """
+    last_commit = state.get("last_git_commit", "")
+    if not last_commit:
+        return True, "无 git commit 记录（跳过校验）"
+
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            capture_output=True, text=True, cwd=str(project_root), timeout=10,
+        )
+        if result.returncode != 0:
+            return True, "非 git 仓库（跳过校验）"
+
+        current = result.stdout.strip()
+        if current == last_commit:
+            return True, f"git HEAD 一致 ({current[:8]})"
+
+        # 检查是否有未提交的修改
+        status_result = subprocess.run(
+            ["git", "status", "--porcelain"],
+            capture_output=True, text=True, cwd=str(project_root), timeout=10,
+        )
+        dirty = bool(status_result.stdout.strip())
+
+        msg = f"git HEAD 不一致: 记录={last_commit[:8]}, 当前={current[:8]}"
+        if dirty:
+            msg += "（且有未提交修改）"
+        return False, msg
+
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return True, "git 不可用（跳过校验）"
+
+
+def _get_git_head(project_root: Path) -> str:
+    """获取当前 git HEAD commit hash。"""
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            capture_output=True, text=True, cwd=str(project_root), timeout=10,
+        )
+        if result.returncode == 0:
+            return result.stdout.strip()
+    except Exception:
+        pass
+    return ""
+
+
 def handle_resume(args) -> int:
     """Handle `sycli resume` command - resume an interrupted optimization."""
     project_root = Path(args.project_root or ".").resolve()
@@ -63,6 +157,19 @@ def handle_resume(args) -> int:
     info(f"Status was: {status}")
     info(f"Task: {task}")
 
+    # ── E4: 进展摘要 ──
+    info("")
+    info("── 进展摘要 ──")
+    _show_resume_summary(sycli_dir, state)
+
+    # ── E4: Git 状态校验 ──
+    info("")
+    info("── Git 状态校验 ──")
+    is_consistent, git_msg = _verify_git_state(project_root, state)
+    info(f"  {git_msg}")
+    if not is_consistent:
+        warning("代码可能已被外部修改，优化结果可能不可预测。")
+
     # Initialize components
     try:
         llm = create_llm(config.llm, streaming=True)

sycli/mode/create.py

@@ -12,7 +12,7 @@ from typing import Any
 from deepagents import create_deep_agent
 from deepagents.backends.local_shell import LocalShellBackend
 from langchain_core.language_models import BaseChatModel
-from langgraph.checkpoint.memory import MemorySaver
+from sycli.rl.checkpoint import FileCheckpointer
 
 from sycli.agents.factory import build_subagents, _memory_middleware, _inject_project_root
 from sycli.agents.prompts import ARCHITECT_PROMPT, DATA_ANALYST_PROMPT, ORCHESTRATOR_PROMPT
@@ -119,7 +119,7 @@ async def run_create(
     header("Phase 3: Build & Iterate")
 
     subagents = build_subagents(config, llm, backend, project_name, mode="create", project_root=str(sycli_dir.parent))
-    checkpointer = MemorySaver()
+    checkpointer = FileCheckpointer(sycli_dir / "checkpoints")
     thread_id = f"sycli-create-{project_name}-{uuid.uuid4().hex[:8]}"
 
     agent = create_deep_agent(
@@ -355,7 +355,7 @@ async def _run_architect_phase(
         system_prompt=_inject_project_root(ARCHITECT_PROMPT, str(backend.cwd)),
         subagents=[researcher_subagent],
         memory=[],
-        checkpointer=MemorySaver(),
+        checkpointer=FileCheckpointer(sycli_dir / "checkpoints"),
         debug=False,
         name="sycli-architect",
     )
@@ -422,7 +422,7 @@ async def _run_data_analyst_phase(
         system_prompt=_inject_project_root(DATA_ANALYST_PROMPT, str(backend.cwd)),
         subagents=[researcher_subagent],
         memory=[],
-        checkpointer=MemorySaver(),
+        checkpointer=FileCheckpointer(sycli_dir / "checkpoints"),
         debug=False,
         name="sycli-data-analyst",
     )

sycli/models/config_models.py

@@ -76,6 +76,7 @@ class RLSettings(BaseModel):
     convergence_strategy: str = "window"  # window | ema | patience
     convergence_threshold: float = 0.05
     convergence_window_size: int = 10
+    convergence_near_target_margin: float = 0.02  # 接近目标时的容差（#8）
     regression_penalty_weight: float = 0.3
     auto_fix_compilation: bool = True
     auto_fix_max_retries: int = 5
@@ -84,6 +85,13 @@ class RLSettings(BaseModel):
     exploration_epsilon_start: float = 0.3
     exploration_epsilon_end: float = 0.05
     exploration_epsilon_decay: float = 0.95
+    accept_threshold: float = 0.8  # ACCEPT 决策的准确率阈值，默认 0.8（#4）
+    experience_keep_rounds: int = 30  # 经验存储保留的最近轮数（#15）
+    perturbation_restart: bool = True  # 停滞但未达标时是否扰动重启（#10）
+    max_bandit_arms: int = 20  # Bandit 最大臂数量，超过时淘汰低效臂（#6）
+    direction_correction_enabled: bool = True  # 是否启用方向纠偏（E2）
+    direction_correction_rollback_threshold: int = 3  # 连续 ROLLBACK 触发数
+    direction_correction_decline_rounds: int = 5  # 持续下降触发轮数
 
 
 class MemorySettings(BaseModel):