@baimingtao/lbs-agent 1.0.0

package/interfaces/api/_impl/server.py

@@ -0,0 +1,1480 @@
+"""FastAPI 服务 —— 把 LBS Agent 运行时暴露给 React UI。"""
+
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+import json
+import os
+import re
+import sys
+import time
+import uuid
+from contextlib import asynccontextmanager
+from dataclasses import asdict, is_dataclass
+from pathlib import Path
+from typing import Any
+
+from application.container import AgentSystemContainer
+from application.runtime_paths import RuntimePaths
+from fastapi import FastAPI, File, Form, HTTPException, UploadFile, WebSocket, WebSocketDisconnect
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+
+PROJECT_ROOT = Path(__file__).resolve().parents[3]
+RUNTIME_PATHS = RuntimePaths.for_project(PROJECT_ROOT).ensure()
+SESSION_ROOT = RUNTIME_PATHS.sessions
+UPLOAD_ROOT = RUNTIME_PATHS.uploads
+FRONTEND_DIST = PROJECT_ROOT / "interfaces" / "web" / "frontend" / "dist"
+
+# Agent 执行专用线程池：与 asyncio 默认线程池隔离，
+# 防止慢 LLM 调用耗尽默认线程池导致 API 端点全部 hang。
+_AGENT_EXECUTOR = concurrent.futures.ThreadPoolExecutor(
+    max_workers=4,
+    thread_name_prefix="agent-exec",
+)
+
+ATTACHMENT_TEXT_EXTS = {".txt", ".md", ".markdown", ".json", ".yaml", ".yml", ".csv",
+                        ".log", ".py", ".js", ".ts", ".tsx", ".jsx", ".html", ".css",
+                        ".xml", ".ini", ".toml", ".sh", ".sql"}
+ATTACHMENT_PREVIEW_CHARS = 2000
+ATTACHMENT_MAX_TEXT_SIZE = 256 * 1024  # 256KB
+ATTACHMENT_MAX_UPLOAD_SIZE = 10 * 1024 * 1024  # 10MB
+SAFE_RUNTIME_ID = re.compile(r"^[A-Za-z0-9_-]{1,128}$")
+
+
+def _safe_runtime_path(root: Path, identifier: str, *, suffix: str = "") -> Path | None:
+    if not identifier or not SAFE_RUNTIME_ID.fullmatch(identifier):
+        return None
+    base = root.resolve()
+    candidate = (base / f"{identifier}{suffix}").resolve()
+    try:
+        candidate.relative_to(base)
+    except ValueError:
+        return None
+    return candidate
+
+
+def _is_text_attachment(path: Path) -> bool:
+    if path.suffix.lower() not in ATTACHMENT_TEXT_EXTS:
+        return False
+    if path.stat().st_size > ATTACHMENT_MAX_TEXT_SIZE:
+        return False
+    return True
+
+
+def _build_attachment_context(session_id: str) -> tuple[str, list[dict[str, Any]]]:
+    """收集该 session 下的附件，构造注入 Agent 的 context 字符串 + 元数据列表。"""
+    used: list[dict[str, Any]] = []
+    sess_dir = _safe_runtime_path(UPLOAD_ROOT, session_id)
+    if sess_dir is None or not sess_dir.is_dir():
+        return "", used
+    files = sorted([p for p in sess_dir.iterdir() if p.is_file()])
+    if not files:
+        return "", used
+    lines = ["[附件上下文] 以下文件已上传到当前会话，Agent 可使用 read_file/terminal 访问其完整内容："]
+    for path in files:
+        try:
+            size = path.stat().st_size
+        except OSError:
+            continue
+        entry: dict[str, Any] = {
+            "name": path.name,
+            "path": str(path),
+            "size": size,
+            "has_preview": False,
+        }
+        lines.append(f"- {path.name} ({size} bytes, path={path})")
+        if _is_text_attachment(path):
+            try:
+                text = path.read_text(encoding="utf-8", errors="replace")
+            except Exception:
+                text = ""
+            if text:
+                preview = text[:ATTACHMENT_PREVIEW_CHARS]
+                ellipsis = "\n…(已截断)" if len(text) > ATTACHMENT_PREVIEW_CHARS else ""
+                lines.append(f"  preview:\n```\n{preview}{ellipsis}\n```")
+                entry["has_preview"] = True
+        else:
+            reason = "二进制文件" if path.suffix.lower() not in ATTACHMENT_TEXT_EXTS else "文件过大"
+            lines.append(f"  preview: {reason}，请用 read_file 或 terminal 工具访问完整内容。")
+        used.append(entry)
+    return "\n".join(lines), used
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+@asynccontextmanager
+async def _lifespan(_app: FastAPI):
+    host = _container()
+    # P3-3: 启动时立即执行恢复
+    if hasattr(host, 'startup_recovery'):
+        try:
+            host.startup_recovery()
+        except Exception:
+            pass
+    host.start_cron_loop()
+    try:
+        yield
+    finally:
+        _shutdown_host_container()
+
+
+app = FastAPI(title="Neko Orchestrator API", version="1.0.0", lifespan=_lifespan)
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["http://localhost:5173", "http://127.0.0.1:5173"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+def _load_config():
+    from config.config import load_config
+    return load_config()
+
+
+_HOST_CONTAINER: AgentSystemContainer | None = None
+
+
+def _container() -> AgentSystemContainer:
+    global _HOST_CONTAINER
+    if _HOST_CONTAINER is None:
+        _HOST_CONTAINER = AgentSystemContainer(config=_load_config(), project_root=PROJECT_ROOT)
+    _HOST_CONTAINER.models_yaml_path_override = _models_yaml_path()
+    _HOST_CONTAINER.agents_yaml_path_override = _agents_yaml_path()
+    _HOST_CONTAINER.mcp_registry_path_override = _mcp_yaml_path()
+    return _HOST_CONTAINER
+
+
+def _shutdown_host_container() -> None:
+    global _HOST_CONTAINER
+    if _HOST_CONTAINER is not None:
+        _HOST_CONTAINER.shutdown()
+        _HOST_CONTAINER = None
+
+
+def _reload_container_config() -> None:
+    """Reload config from YAML files into the live container.
+
+    After any YAML write (model switch, agent binding, provider edit),
+    the in-memory config and cached orchestrator must be refreshed so
+    the next agent run picks up the new settings — not the stale
+    startup-time snapshot.
+    """
+    container = _container()
+    # 1. Reload config from disk
+    fresh = _load_config()
+    container.config = fresh
+    # 2. Invalidate cached orchestrator so it rebuilds with new config
+    if container._orchestrator is not None:
+        try:
+            container._orchestrator.shutdown()
+        except Exception:
+            pass
+        container._orchestrator = None
+    # 3. Invalidate cached runtime_factory — it holds the old config snapshot
+    #    and would build AgentConfig with stale model/provider values.
+    if container._runtime_factory is not None:
+        try:
+            container._runtime_factory.close()
+        except Exception:
+            pass
+        container._runtime_factory = None
+
+
+def _jsonable(value: Any) -> Any:
+    if is_dataclass(value):
+        return asdict(value)
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, dict):
+        return {str(k): _jsonable(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_jsonable(v) for v in value]
+    return value
+
+
+def _get_models() -> list[dict[str, Any]]:
+    config = _load_config()
+    models: list[dict[str, Any]] = []
+    for provider_name, provider in config.models.providers.items():
+        for model in provider.models or []:
+            models.append({
+                "name": model,
+                "provider": provider_name,
+                "healthy": bool(provider.all_keys),
+                "configured": bool(provider.all_keys),
+                "default": (
+                    provider_name == config.models.default_provider
+                    and model == config.models.default_model
+                ),
+            })
+    return models
+
+
+def _get_usage() -> dict[str, Any]:
+    return _container().model_service().usage_summary()
+
+
+def _get_cron() -> list[dict[str, Any]]:
+    return [_cron_payload(job) for job in _container().cron_service().list_jobs()]
+
+
+def _get_sessions() -> list[dict[str, Any]]:
+    service = _container().session_service()
+    visible = []
+    for item in service.list_sessions(limit=1_000_000):
+        payload = service.load_session(item.session_id) or {}
+        conversation = payload.get("conversation_messages", []) or []
+        provider_messages = payload.get("messages", []) or []
+        d = _jsonable(item)
+        visible.append({**d, "created_at": item.created_at, "updated_at": item.updated_at})
+        if len(visible) >= 100:
+            break
+    return visible
+
+
+def _get_skills() -> list[dict[str, Any]]:
+    rows: list[dict[str, Any]] = []
+    bases = [
+        (PROJECT_ROOT / "extensions" / "skills" / "builtin", "builtin"),
+        (PROJECT_ROOT / "extensions" / "skills" / "optional", "optional"),
+    ]
+    for base, source_name in bases:
+        if not base.is_dir():
+            continue
+        for path in sorted(base.rglob("SKILL.md")):
+            text = path.read_text(encoding="utf-8", errors="replace")
+            title = next((line.lstrip("# ").strip() for line in text.splitlines() if line.startswith("#")), path.parent.name)
+            rows.append({"name": path.parent.name, "title": title, "path": str(path.relative_to(PROJECT_ROOT)), "source": source_name})
+    return rows
+
+
+def _get_mcp_servers() -> list[dict[str, Any]]:
+    candidates = [PROJECT_ROOT / "config" / "mcp.yaml", PROJECT_ROOT / "mcp.yaml", Path.home() / ".hermes" / "config.yaml"]
+    for path in candidates:
+        if not path.exists():
+            continue
+        try:
+            import yaml
+            raw = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+            servers = raw.get("mcp_servers") or raw.get("mcp") or {}
+            if isinstance(servers, dict):
+                return [{"name": name, "transport": value.get("transport", "stdio") if isinstance(value, dict) else "stdio", "enabled": value.get("enabled", True) if isinstance(value, dict) else True, "config_path": str(path)} for name, value in servers.items()]
+        except Exception:
+            continue
+    return []
+
+
+def _get_souls() -> list[dict[str, str]]:
+    souls_dir = PROJECT_ROOT / "souls"
+    result: list[dict[str, str]] = []
+    if not souls_dir.is_dir():
+        return result
+    for path in sorted(souls_dir.glob("*.md")):
+        desc = ""
+        for line in path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if line and not line.startswith(("#", "---")):
+                desc = line[:120]
+                break
+        result.append({"name": path.stem, "desc": desc})
+    return result
+
+
+def _models_yaml_path() -> Path:
+    return PROJECT_ROOT / "runtime" / "core" / "llm" / "registry" / "models.yaml"
+
+
+def _agents_yaml_path() -> Path:
+    return PROJECT_ROOT / "runtime" / "core" / "sub_agents" / "agents.yaml"
+
+
+def _mcp_yaml_path() -> Path:
+    for path in (PROJECT_ROOT / "config" / "mcp.yaml", PROJECT_ROOT / "mcp.yaml"):
+        if path.exists():
+            return path
+    return PROJECT_ROOT / "config" / "mcp.yaml"
+
+
+def _write_yaml(path: Path, mutate) -> None:
+    """统一的 YAML 原子写：内部委托给 ModelService / AgentService。
+
+    保留此函数是为了不让 server 端点直接 new yaml 写文件。
+    """
+    import yaml
+    path_str = str(path)
+    # 根据路径判断走哪个 service
+    if "models.yaml" in path_str:
+        svc = _container().model_service()
+        svc.write_yaml(path, mutate)
+        return
+    elif "agents.yaml" in path_str:
+        svc = _container().agent_service()
+        svc.write_yaml(path, mutate)
+        return
+    elif "mcp.yaml" in path_str or path_str.endswith("mcp.json"):
+        # MCP 配置统一走 McpService / McpRegistry
+        registry = _container().mcp_service()._registry()
+        config = {"mcp_servers": {s.name: s.to_dict() for s in registry.list_servers(include_disabled=True)}}
+        mutate(config)
+        servers = config.get("mcp_servers", {}) or {}
+        # 重建 registry，保持单事实源
+        existing = {s.name for s in registry.list_servers(include_disabled=True)}
+        incoming = set(servers.keys())
+        for name in sorted(existing - incoming):
+            registry.remove(name)
+        for name, spec in servers.items():
+            spec = spec or {}
+            registry.upsert(
+                name,
+                command=spec.get("command", ""),
+                args=list(spec.get("args", []) or []),
+                env=dict(spec.get("env", {}) or {}),
+                transport=spec.get("transport", "stdio"),
+                url=spec.get("url", ""),
+                headers=dict(spec.get("headers", {}) or {}),
+                description=spec.get("description", ""),
+                enabled=bool(spec.get("enabled", True)),
+            )
+        return
+    else:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        config = (yaml.safe_load(path.read_text(encoding="utf-8")) or {}) if path.exists() else {}
+        mutate(config)
+        path.write_text(
+            yaml.safe_dump(config, allow_unicode=True, default_flow_style=False, sort_keys=False),
+            encoding="utf-8",
+        )
+        return
+
+
+def _get_current_soul() -> str:
+    config = _load_config()
+    return str(config.models.raw.get("default", {}).get("soul", "default"))
+
+
+def _get_agents() -> list[dict[str, Any]]:
+    config = _load_config()
+    return [
+        {
+            "name": name,
+            "display_name": agent.display_name,
+            "model": agent.model,
+            "provider": agent.provider,
+            "tools": list(agent.tools),
+        }
+        for name, agent in config.agents.agents.items()
+    ]
+
+
+from interfaces.api._impl._models import (
+    ModelSelection, AgentModelSelection, AgentConfigMutation,
+    McpServerMutation, McpToggleMutation, McpConnectMutation, CronCreate, SessionCreate,
+    ProviderMutation, ModelAddition, SoulCreatePayload, SkillPatch,
+    ChatRequest,
+)
+
+
+def _mask_api_key(key: str) -> str:
+    if not key:
+        return ""
+    if len(key) <= 8:
+        return "***"
+    return f"{key[:3]}***{key[-3:]}"
+
+
+def _serialize_provider(name: str, raw: dict[str, Any], is_builtin: bool) -> dict[str, Any]:
+    api_key = str(raw.get("api_key", "") or "")
+    api_keys = [str(k) for k in (raw.get("api_keys", []) or []) if str(k)]
+    models = list(raw.get("models", []) or [])
+    masked_keys = [_mask_api_key(k) for k in ([api_key] if api_key else []) + api_keys]
+    return {
+        "name": name,
+        "display_name": str(raw.get("display_name", name)),
+        "base_url": str(raw.get("base_url", "")),
+        "api_mode": str(raw.get("api_mode", "chat_completions")),
+        "models": models,
+        "description": str(raw.get("description", "")),
+        "is_builtin": is_builtin,
+        "has_api_key": bool(api_key or api_keys),
+        "api_key_masked": _mask_api_key(api_key),
+        "api_keys_masked": masked_keys,
+        "key_count": len(masked_keys),
+        "max_retries": raw.get("max_retries"),
+        "request_timeout": raw.get("request_timeout"),
+    }
+
+
+def _fetch_provider_models(name: str, spec: dict[str, Any]) -> list[str]:
+    """真正调用供应商 API 获取模型列表（类似 Hermes / cc-switch 的行为）。
+
+    支持：
+    - OpenAI 兼容：GET {base_url}/models 或 {base_url}/v1/models
+    - Anthropic：GET {base_url}/v1/models
+    返回模型 id 列表。
+    """
+    import httpx
+
+    base_url = (spec.get("base_url") or "").rstrip("/")
+    api_mode = spec.get("api_mode") or "chat_completions"
+    api_key = ""
+    # 从 api_keys 中取第一个非空 key
+    for k in (spec.get("api_keys") or []):
+        if k and k.strip():
+            api_key = k.strip()
+            break
+    if not api_key:
+        api_key = (spec.get("api_key") or "").strip()
+
+    if not base_url:
+        raise HTTPException(status_code=400, detail=f"供应商 {name} 未配置 base_url")
+
+    # 构建候选 URLs
+    candidates: list[str] = []
+    # Anthropic 模式：try /v1/models
+    if api_mode == "anthropic_messages":
+        candidates.append(f"{base_url}/v1/models")
+        candidates.append(f"{base_url}/models")
+    else:
+        # OpenAI 兼容
+        candidates.append(f"{base_url}/models")
+        candidates.append(f"{base_url}/v1/models")
+
+    headers: dict[str, str] = {}
+    if api_mode == "anthropic_messages":
+        headers["x-api-key"] = api_key
+        headers["anthropic-version"] = "2023-06-01"
+    else:
+        headers["Authorization"] = f"Bearer {api_key}"
+
+    last_error = ""
+    for url in candidates:
+        try:
+            with httpx.Client(timeout=15) as client:
+                resp = client.get(url, headers=headers)
+                if resp.status_code == 404:
+                    continue
+                if resp.status_code != 200:
+                    last_error = f"{url} → HTTP {resp.status_code}"
+                    continue
+                data = resp.json()
+                # OpenAI 格式: { data: [{ id: "model-name" }] }
+                if isinstance(data, dict) and "data" in data:
+                    models = [item.get("id", "") for item in data["data"] if isinstance(item, dict)]
+                # Anthropic 格式: { data: [{ id: "model-name" }] }
+                elif isinstance(data, dict) and "models" in data:
+                    models = [item.get("id", item.get("name", "")) for item in data["models"] if isinstance(item, dict)]
+                elif isinstance(data, list):
+                    models = [item.get("id", item.get("name", "")) for item in data if isinstance(item, dict)]
+                else:
+                    models = []
+                models = [m for m in models if m and m.strip()]
+                if models:
+                    return sorted(set(models))
+        except httpx.ConnectError as e:
+            last_error = f"{url} → 连接失败：{e}"
+        except httpx.TimeoutException:
+            last_error = f"{url} → 超时"
+        except Exception as e:
+            last_error = f"{url} → {e}"
+
+    raise HTTPException(
+        status_code=502,
+        detail=f"无法从 {name} 获取模型列表。最后错误：{last_error or '所有候选 URL 均未返回有效数据'}"
+    )
+
+
+def _load_models_yaml_raw() -> dict[str, Any]:
+    path = _models_yaml_path()
+    if not path.exists():
+        return {"default": {}, "builtin": {}, "custom": {}}
+    import yaml
+    raw = yaml.safe_load(path.read_text(encoding="utf-8")) or {"default": {}, "builtin": {}, "custom": {}}
+    # 给 builtin provider 注入出厂默认 models（如果 yaml 没声明）
+    from config.config import BUILTIN_DEFAULT_MODELS
+    builtin = raw.setdefault("builtin", {})
+    for name, spec in builtin.items():
+        if not isinstance(spec, dict):
+            continue
+        existing = list(spec.get("models", []) or [])
+        if existing:
+            continue
+        defaults = BUILTIN_DEFAULT_MODELS.get(name, [])
+        if defaults:
+            spec["models"] = defaults
+    return raw
+
+
+COMMAND_GROUPS = [
+    {
+        "key": "capabilities", "title": "能力配置", "commands": [
+            {"icon": "🤖", "name": "models", "label": "模型配置", "description": "查看供应商、模型与默认路由"},
+            {"icon": "🔧", "name": "tools", "label": "工具配置", "description": "查看已注册工具及运行配置"},
+            {"icon": "🧩", "name": "skills", "label": "Skill 配置", "description": "查看本地 Skill 能力包"},
+            {"icon": "🔌", "name": "mcp", "label": "MCP 配置", "description": "查看 MCP Server 配置与状态"},
+        ],
+    },
+    {
+        "key": "runtime", "title": "运行中心", "commands": [
+            {"icon": "👥", "name": "agents", "label": "Agent 列表", "description": "查看 Agent、模型和工具权限"},
+            {"icon": "⚡", "name": "workers", "label": "执行记录", "description": "查看最近的 Worker 执行记录"},
+            {"icon": "📈", "name": "usage", "label": "Token 请求", "description": "查看 Token、请求次数与费用"},
+        ],
+    },
+    {
+        "key": "workspace", "title": "工作区", "commands": [
+            {"icon": "💬", "name": "sessions", "label": "会话工作台", "description": "实时 Agent 会话、任务执行与上下文管理", "requires_task": True},
+            {"icon": "📋", "name": "session-history", "label": "会话历史", "description": "浏览、搜索和查看历史会话详情"},
+            {"icon": "📎", "name": "files", "label": "文件管理", "description": "上传并管理会话附件"},
+        ],
+    },
+    {
+        "key": "automation", "title": "自动化", "commands": [
+            {"icon": "⏰", "name": "cron", "label": "定时任务", "description": "查看全部定时任务及下次执行时间"},
+            {"icon": "🎭", "name": "souls", "label": "角色配置", "description": "查看可用角色与当前角色"},
+        ],
+    },
+]
+
+
+def _cron_payload(job: Any) -> dict[str, Any]:
+    raw = _jsonable(job)
+    raw.setdefault("job_id", str(getattr(job, "job_id", getattr(job, "id", ""))))
+    raw.setdefault("enabled", bool(getattr(job, "enabled", True)))
+    raw.setdefault("task", str(getattr(job, "task", "")))
+    raw.setdefault("agent_name", str(getattr(job, "agent_name", getattr(job, "agent", ""))))
+    value = getattr(job, "next_run_at", "")
+    raw.setdefault("next_run_at", value.isoformat() if hasattr(value, "isoformat") else str(value or ""))
+    return raw
+
+
+def _get_workers() -> list[dict[str, Any]]:
+    records = _container().session_service().worker_records(limit=20)
+    labels = {
+        "running": "运行中", "completed": "已完成", "success": "已完成",
+        "failed": "失败", "error": "失败", "stalled": "已停滞",
+    }
+    return [
+        {**record, "status_label": labels.get(str(record.get("status", "")).lower(), "未知")}
+        for record in records
+    ]
+
+
+def _validate_agent_task(agent_name: str, task: str) -> None:
+    if not task.strip():
+        raise HTTPException(status_code=400, detail="请输入要执行的任务")
+    if agent_name not in _load_config().agents.agents:
+        raise HTTPException(status_code=404, detail=f"未知 Agent：{agent_name}")
+
+
+@app.get("/api/status")
+async def get_status():
+    config = _load_config()
+    return {
+        "status": "running",
+        "project": "LBS Agent",
+        "version": "1.0.0",
+        "timestamp": time.time(),
+        "default_provider": config.models.default_provider,
+        "default_model": config.models.default_model,
+        "agents": len(config.agents.agents),
+    }
+
+
+@app.get("/api/models")
+async def get_models():
+    return {"models": _get_models()}
+
+
+@app.post("/api/models/default")
+async def set_default_model(selection: ModelSelection):
+    # 主路由必须有值，不允许清空
+    if not selection.provider or not selection.model:
+        raise HTTPException(status_code=400, detail="主路由的供应商和模型不能为空")
+    provider = _load_config().models.providers.get(selection.provider)
+    if not provider or selection.model not in provider.models:
+        raise HTTPException(status_code=404, detail="模型不存在或不属于该供应商")
+    _container().model_service().set_default_model(selection.provider, selection.model)
+    # 自动同步：未绑定模型的 Agent 继承默认模型
+    synced = _sync_unbound_agents(selection.provider, selection.model)
+    _reload_container_config()
+    return {"ok": True, "provider": selection.provider, "model": selection.model, "synced_agents": synced}
+
+
+def _sync_unbound_agents(provider: str, model: str) -> list[str]:
+    """将未绑定 provider/model 的 Agent 同步为默认模型，返回已同步的 Agent 名列表。"""
+    import yaml
+    import os as _os
+    from threading import RLock
+    svc = _container().agent_service()
+    agents_path = svc._agents_yaml_path()
+    lock = getattr(svc, "_yaml_lock", RLock())
+    synced: list[str] = []
+    with lock:
+        raw = yaml.safe_load(agents_path.read_text(encoding="utf-8")) or {}
+        agents = raw.get("agents", {})
+        changed = False
+        for name, cfg in agents.items():
+            if not isinstance(cfg, dict):
+                continue
+            if not cfg.get("provider") or not cfg.get("model"):
+                cfg["provider"] = provider
+                cfg["model"] = model
+                synced.append(name)
+                changed = True
+        if changed:
+            tmp = agents_path.with_suffix(agents_path.suffix + ".tmp")
+            tmp.write_text(
+                yaml.safe_dump(raw, allow_unicode=True, default_flow_style=False, sort_keys=False),
+                encoding="utf-8",
+            )
+            _os.replace(tmp, agents_path)
+    return synced
+
+
+@app.get("/api/providers")
+async def get_providers():
+    # 走 ModelService（应用层入口）
+    return {"providers": _container().model_service().list_providers_yaml()}
+
+
+def _resolve_provider_section(name: str) -> tuple[str, dict[str, Any]]:
+    """返回 (section_name, bucket_dict)。builtin 不可删除。
+
+    内部委托给 ModelService（应用层入口）。
+    """
+    return _container().model_service().get_provider_section(name)
+
+
+def _reject_builtin_delete(name: str) -> None:
+    raw = _container().model_service().read_models_yaml()
+    if name in (raw.get("builtin") or {}):
+        raise HTTPException(status_code=400, detail=f"内置供应商 {name} 不可删除，只能填 key 与加 model")
+
+
+@app.put("/api/providers/{name}")
+async def upsert_provider(name: str, payload: ProviderMutation):
+    if not name.replace("-", "").replace("_", "").isalnum():
+        raise HTTPException(status_code=400, detail="供应商名称仅允许字母、数字、-、_")
+    # 走 ModelService（应用层入口）
+    raw = _container().model_service().read_models_yaml()
+    is_builtin = name in (raw.get("builtin") or {})
+    payload_dict = payload.model_dump(exclude_unset=True) if hasattr(payload, "model_dump") else dict(payload)
+    ok = _container().model_service().upsert_provider_yaml(name, payload_dict, is_builtin=is_builtin)
+    _reload_container_config()
+    fresh = _container().model_service().read_models_yaml()
+    section = "builtin" if is_builtin else "custom"
+    return {
+        "ok": ok,
+        "name": name,
+        "provider": _container().model_service().serialize_provider(name, fresh.get(section, {}).get(name, {}), is_builtin),
+    }
+
+
+@app.post("/api/providers/{name}/models/fetch")
+async def fetch_provider_models(name: str):
+    try:
+        models = _container().model_service().fetch_provider_models(name, _fetch_provider_models)
+        _reload_container_config()
+    except HTTPException:
+        raise
+    except Exception as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    return {"ok": True, "name": name, "models": models}
+
+
+@app.delete("/api/providers/{name}")
+async def delete_provider(name: str):
+    _reject_builtin_delete(name)
+    # 走 ModelService（应用层入口）
+    ok = _container().model_service().delete_provider(name)
+    _reload_container_config()
+    if not ok:
+        raise HTTPException(status_code=404, detail=f"供应商 {name} 不存在")
+    return {"ok": True, "name": name}
+
+
+@app.post("/api/providers/{name}/models")
+async def add_model(name: str, payload: ModelAddition):
+    section, _ = _container().model_service().get_provider_section(name)
+    model = payload.name.strip()
+    if not model:
+        raise HTTPException(status_code=400, detail="模型名不能为空")
+    if section == "builtin" and model not in {"claude-sonnet-4", "claude-opus-4", "claude-haiku-4"}:
+        # builtin 不允许任意 model 名（demo 限制）
+        pass
+    try:
+        ok = _container().model_service().add_model_yaml(name, model)
+    except ValueError as e:
+        raise HTTPException(status_code=409, detail=str(e))
+    except KeyError:
+        raise HTTPException(status_code=404, detail=f"供应商 {name} 不存在")
+    return {"ok": ok, "name": name, "model": model}
+@app.delete("/api/providers/{name}/models/{model:path}")
+async def remove_model(name: str, model: str):
+    # 走 ModelService（应用层入口）
+    try:
+        ok = _container().model_service().remove_model_yaml(name, model)
+    except Exception:
+        ok = False
+    if not ok:
+        raise HTTPException(status_code=404, detail=f"模型 {model} 不在供应商 {name} 下")
+    return {"ok": ok, "name": name, "model": model}
+
+
+@app.get("/api/sessions")
+async def get_sessions(q: str = ""):
+    if q.strip():
+        service = _container().session_service()
+        raw = service.search_sessions(q.strip(), limit=50)
+        results = []
+        for r in raw:
+            sid = r.get("session_id", "")
+            payload = service.load_session(sid) or {}
+            results.append({
+                **r,
+                "title": payload.get("title", ""),
+                "status": payload.get("status", ""),
+                "iterations": payload.get("iterations", 0),
+                "total_tool_calls": payload.get("total_tool_calls", 0),
+                "duration_seconds": payload.get("duration_seconds", 0.0),
+                "updated_at": payload.get("updated_at", r.get("created_at", "")),
+            })
+        return {"sessions": results}
+    return {"sessions": _get_sessions()}
+
+
+@app.post("/api/sessions")
+async def create_session(payload: SessionCreate):
+    return _container().session_service().create_session(payload.title)
+
+
+@app.get("/api/sessions/{session_id}")
+async def get_session_detail(session_id: str):
+    payload = _container().session_service().load_session(session_id)
+    if not payload:
+        raise HTTPException(status_code=404, detail="会话不存在")
+    # UI 展示消息与 AgentLoop provider history 分离。
+    provider_messages = payload.get("messages", []) or []
+    conversation_messages = payload.get("conversation_messages", []) or []
+    report = _container().session_service().report_session(session_id)
+    latest_context = report.get("context_preflight", {}).get("latest", {}) or {}
+    payload["conversation_messages"] = conversation_messages
+    payload["messages"] = conversation_messages
+    payload["provider_message_count"] = len(provider_messages)
+    # 历史会话可能没有 context_preflight 数据，用 agent 默认 context_length 兜底
+    agent_ctx_length = 0
+    try:
+        agent_name = payload.get("agent_name", "chat")
+        cfg = _load_config()
+        if agent_name in cfg.agents.agents:
+            agent_ctx_length = getattr(cfg.agents.agents[agent_name], "context_length", 0) or 0
+    except Exception:
+        pass
+    ctx_window = latest_context.get("context_window", 0) or agent_ctx_length
+    # 从最后一条 assistant 消息恢复 context_info（新格式）或 session 顶层
+    last_assistant_ctx = {}
+    for m in reversed(conversation_messages):
+        if isinstance(m, dict) and m.get("role") == "assistant" and m.get("context_info"):
+            last_assistant_ctx = m["context_info"]
+            break
+    ctx_tokens = last_assistant_ctx.get("current_tokens") or latest_context.get("current_tokens") or 0
+    payload["observability"] = {
+        "context_window": ctx_window,
+        "current_tokens": ctx_tokens,
+        "percent": (ctx_tokens / ctx_window * 100) if ctx_window else 0,
+        "threshold": last_assistant_ctx.get("threshold") or latest_context.get("threshold", 0),
+        "compression_count": len(payload.get("compression_history", [])) or report.get("context_preflight", {}).get("compression_count", 0),
+        "compression_enabled": True,
+        "last_request": payload.get("usage_summary", {}) or {},
+    }
+    # 从 session 恢复 model 和 usage
+    payload["model"] = payload.get("last_model", "")
+    u = payload.get("usage_summary", {}) or {}
+    payload["usage"] = {"input": u.get("total_input_tokens", 0), "output": u.get("total_output_tokens", 0), "cost": str(u.get("total_cost_usd", 0.0))}
+    payload["run_report"] = {
+        "iterations": report.get("iterations", 0),
+        "total_tool_calls": report.get("total_tool_calls", 0),
+        "step_count": report.get("step_count", 0),
+        "run_trace_count": report.get("run_trace_count", 0),
+        "status": report.get("status", payload.get("status", "")),
+        "error": report.get("error", payload.get("error", "")),
+    }
+    return payload
+
+
+@app.delete("/api/sessions/{session_id}")
+async def delete_session(session_id: str):
+    """删除会话及其 sidecar 文件。"""
+    store = _container().build_session_store()
+    path = store._find_path_by_session_id(session_id)
+    if path is None:
+        raise HTTPException(status_code=404, detail="会话不存在")
+    deleted = store.delete_session_files(path)
+    return {"ok": deleted, "session_id": session_id}
+
+
+class SessionPatch(BaseModel):
+    title: str = ""
+
+
+@app.patch("/api/sessions/{session_id}")
+async def patch_session(session_id: str, patch: SessionPatch):
+    """更新会话标题。"""
+    service = _container().session_service()
+    ok = service.rename_session(session_id, patch.title)
+    if not ok:
+        raise HTTPException(status_code=404, detail="会话不存在")
+    return {"ok": True, "session_id": session_id, "title": patch.title}
+
+
+@app.post("/api/files/upload")
+async def upload_file(file: UploadFile = File(...), session_id: str = Form("")):
+    safe_name = Path(file.filename or "upload.bin").name
+    bucket = session_id or "shared"
+    target_dir = _safe_runtime_path(UPLOAD_ROOT, bucket)
+    if target_dir is None:
+        raise HTTPException(status_code=400, detail="非法会话 ID")
+    data = await file.read(ATTACHMENT_MAX_UPLOAD_SIZE + 1)
+    if len(data) > ATTACHMENT_MAX_UPLOAD_SIZE:
+        raise HTTPException(status_code=413, detail="附件过大")
+    target_dir.mkdir(parents=True, exist_ok=True)
+    target = target_dir / safe_name
+    target.write_bytes(data)
+    now = time.strftime("%Y-%m-%dT%H:%M:%S")
+    attachment = {"name": safe_name, "path": str(target), "size": len(data),
+                  "session_id": bucket, "uploaded_at": now}
+    if bucket != "shared":
+        _container().session_service().add_attachment(bucket, attachment)
+    return attachment
+
+
+@app.get("/api/files")
+async def get_files():
+    files = [] if not UPLOAD_ROOT.exists() else [
+        {"name": path.name, "path": str(path), "size": path.stat().st_size,
+         "session_id": path.parent.name}
+        for path in sorted(UPLOAD_ROOT.rglob("*")) if path.is_file()
+    ]
+    return {"files": files}
+
+
+@app.delete("/api/files/{session_id}/{name}")
+async def delete_file(session_id: str, name: str):
+    safe = Path(name).name
+    target_dir = _safe_runtime_path(UPLOAD_ROOT, session_id)
+    if target_dir is None:
+        raise HTTPException(status_code=400, detail="非法会话 ID")
+    target = target_dir / safe
+    if not target.exists():
+        raise HTTPException(status_code=404, detail="附件不存在")
+    target.unlink()
+    if session_id != "shared":
+        _container().session_service().remove_attachment(session_id, safe)
+    return {"ok": True, "name": safe, "path": str(target)}
+
+
+@app.get("/api/files/download/{session_id}/{name}")
+async def download_file(session_id: str, name: str):
+    """下载附件文件。"""
+    from fastapi.responses import FileResponse
+    safe = Path(name).name
+    target_dir = _safe_runtime_path(UPLOAD_ROOT, session_id)
+    if target_dir is None:
+        raise HTTPException(status_code=400, detail="非法会话 ID")
+    target = target_dir / safe
+    if not target.exists():
+        raise HTTPException(status_code=404, detail="附件不存在")
+    return FileResponse(str(target), filename=safe)
+
+
+@app.get("/api/cron")
+async def get_cron():
+    return {"jobs": _get_cron()}
+
+
+@app.post("/api/cron")
+async def create_cron(payload: CronCreate):
+    if not payload.name.strip() or not payload.task.strip():
+        raise HTTPException(status_code=400, detail="任务名称和任务内容不能为空")
+    if payload.agent not in _load_config().agents.agents:
+        raise HTTPException(status_code=404, detail=f"未知 Agent：{payload.agent}")
+    try:
+        job = _container().cron_service().create(
+            name=payload.name.strip(), schedule=payload.schedule.strip(), agent=payload.agent,
+            task=payload.task.strip(), context=payload.context.strip(),
+        )
+        result = _jsonable(job)
+        return {"ok": True, "job_id": result.get("job_id", ""), "job": result}
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+@app.post("/api/cron/{job_id}/{action}")
+async def update_cron(job_id: str, action: str):
+    try:
+        changed = _container().cron_service().update(job_id, action)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    if not changed:
+        raise HTTPException(status_code=404, detail="定时任务不存在或状态未变化")
+    return {"ok": True, "job_id": job_id, "action": action}
+
+
+@app.get("/api/usage")
+async def get_usage():
+    return _get_usage()
+
+
+@app.get("/api/soul")
+async def get_soul():
+    name = _get_current_soul()
+    path = PROJECT_ROOT / "souls" / f"{name}.md"
+    return {"name": name, "content": path.read_text(encoding="utf-8") if path.exists() else ""}
+
+
+@app.get("/api/souls")
+async def get_souls():
+    return {"souls": _get_souls(), "current": _get_current_soul()}
+
+
+@app.post("/api/soul/switch")
+async def switch_soul(name: str):
+    if not name.strip():
+        raise HTTPException(status_code=400, detail="soul 名不能为空")
+    # 走 ModelService（应用层入口）
+    ok = _container().model_service().set_soul(name)
+    # 立即刷新 container config，让下次 agent 运行拿到新 soul
+    _reload_container_config()
+    return {"ok": ok, "soul": name}
+
+
+@app.post("/api/souls")
+async def create_soul(payload: SoulCreatePayload):
+    """保存新角色灵魂文件到 souls/ 目录，HTML → Markdown。"""
+    import html
+    import re
+
+    raw_name = payload.name.strip()
+    if not raw_name:
+        raise HTTPException(status_code=400, detail="角色名不能为空")
+    # 安全文件名：只允许字母、数字、下划线、短横、点
+    safe_name = re.sub(r'[^\w\-.]', '_', raw_name)
+    if not safe_name.endswith('.md'):
+        safe_name += '.md'
+    souls_dir = PROJECT_ROOT / "souls"
+    souls_dir.mkdir(parents=True, exist_ok=True)
+    target = souls_dir / safe_name
+    if target.exists():
+        raise HTTPException(status_code=409, detail=f"角色文件 {safe_name} 已存在")
+
+    # 简单 HTML → Markdown 转换
+    md = payload.content
+    md = re.sub(r'<h1[^>]*>(.*?)</h1>', r'# \1', md, flags=re.IGNORECASE | re.DOTALL)
+    md = re.sub(r'<h2[^>]*>(.*?)</h2>', r'## \1', md, flags=re.IGNORECASE | re.DOTALL)
+    md = re.sub(r'<h3[^>]*>(.*?)</h3>', r'### \1', md, flags=re.IGNORECASE | re.DOTALL)
+    md = re.sub(r'<strong[^>]*>(.*?)</strong>', r'**\1**', md, flags=re.IGNORECASE | re.DOTALL)
+    md = re.sub(r'<b[^>]*>(.*?)</b>', r'**\1**', md, flags=re.IGNORECASE | re.DOTALL)
+    md = re.sub(r'<em[^>]*>(.*?)</em>', r'*\1*', md, flags=re.IGNORECASE | re.DOTALL)
+    md = re.sub(r'<u[^>]*>(.*?)</u>', r'\1', md, flags=re.IGNORECASE | re.DOTALL)
+    md = re.sub(r'<s[^>]*>(.*?)</s>', r'~~\1~~', md, flags=re.IGNORECASE | re.DOTALL)
+    md = re.sub(r'<code[^>]*>(.*?)</code>', r'`\1`', md, flags=re.IGNORECASE | re.DOTALL)
+    md = re.sub(r'<blockquote[^>]*>(.*?)</blockquote>', lambda m: '\n> ' + m.group(1).strip().replace('\n', '\n> ') + '\n', md, flags=re.IGNORECASE | re.DOTALL)
+    md = re.sub(r'<ul[^>]*>(.*?)</ul>', lambda m: '\n' + re.sub(r'<li[^>]*>(.*?)</li>', r'- \1', m.group(1), flags=re.IGNORECASE | re.DOTALL) + '\n', md, flags=re.IGNORECASE | re.DOTALL)
+    md = re.sub(r'<ol[^>]*>(.*?)</ol>', lambda m: '\n' + re.sub(r'<li[^>]*>(.*?)</li>', r'1. \1', m.group(1), flags=re.IGNORECASE | re.DOTALL) + '\n', md, flags=re.IGNORECASE | re.DOTALL)
+    md = re.sub(r'<p[^>]*>', '\n', md, flags=re.IGNORECASE)
+    md = re.sub(r'</p>', '\n', md, flags=re.IGNORECASE)
+    md = re.sub(r'<br\s*/?>', '\n', md, flags=re.IGNORECASE)
+    md = re.sub(r'<[^>]+>', '', md)  # 去掉剩余标签
+    md = html.unescape(md)
+    md = re.sub(r'\n{3,}', '\n\n', md).strip()
+
+    target.write_text(md, encoding="utf-8")
+    return {"ok": True, "name": target.stem, "path": str(target)}
+
+@app.get("/api/agents")
+async def get_agents():
+    return {"agents": _get_agents()}
+
+
+@app.get("/api/agents/{agent_name}")
+async def get_agent_detail(agent_name: str):
+    config = _load_config()
+    agent = config.agents.agents.get(agent_name)
+    if not agent:
+        raise HTTPException(status_code=404, detail=f"未知 Agent：{agent_name}")
+    return {
+        "name": agent_name,
+        "display_name": agent.display_name,
+        "description": getattr(agent, "description", "") or "",
+        "provider": agent.provider,
+        "model": agent.model,
+        "fallback_models": list(getattr(agent, "fallback_models", []) or []),
+        "tools": list(agent.tools),
+        "guardrails": list(getattr(agent, "guardrails", []) or []),
+        "verification_rules": list(getattr(agent, "verification_rules", []) or []),
+        "verification_level": getattr(agent, "verification_level", "medium"),
+        "error_strategy": getattr(agent, "error_strategy", ""),
+        "timeout": getattr(agent, "timeout", None),
+        "max_iterations": getattr(agent, "max_iterations", None),
+        "max_retries": getattr(agent, "max_retries", None),
+        "prompt_file": getattr(agent, "prompt_file", "") or "",
+    }
+
+
+@app.put("/api/agents/{agent_name}")
+async def put_agent_full(agent_name: str, payload: AgentConfigMutation):
+    return await update_agent_config(agent_name, payload)
+
+
+@app.post("/api/agents/{agent_name}/model")
+async def set_agent_model(agent_name: str, selection: AgentModelSelection):
+    # 走 AgentService（应用层入口）
+    from fastapi import HTTPException
+    config = _load_config()
+    if agent_name not in config.agents.agents:
+        raise HTTPException(status_code=404, detail=f"未知 Agent：{agent_name}")
+    provider = config.models.providers.get(selection.provider)
+    if not provider or selection.model not in provider.models:
+        raise HTTPException(status_code=400, detail="供应商或模型不存在")
+    ok = _container().agent_service().update_agent(agent_name, {"provider": selection.provider, "model": selection.model})
+    _reload_container_config()
+    return {
+        "ok": ok,
+        "agent": agent_name,
+        "provider": selection.provider,
+        "model": selection.model,
+    }
+@app.patch("/api/agents/{agent_name}/config")
+async def update_agent_config(agent_name: str, payload: AgentConfigMutation):
+    # 走 AgentService（应用层入口）
+    if not _container().agent_service().get_agent_entry(agent_name):
+        raise HTTPException(status_code=404, detail=f"未知 Agent：{agent_name}")
+    values = payload.model_dump(exclude_unset=True)
+    ok = _container().agent_service().update_agent_partial(agent_name, values)
+    return {"ok": ok, "agent": agent_name, "config": values}
+@app.get("/api/tools")
+async def get_tools():
+    return {"tools": _container().tool_service().describe_tools()}
+
+
+@app.get("/api/skills")
+async def get_skills():
+    return {"skills": _container().skill_service().list_skills_api()}
+
+
+@app.get("/api/mcp")
+async def get_mcp():
+    return {"servers": _container().mcp_service().list_servers(include_disabled=True)}
+
+
+@app.get("/api/mcp/status")
+async def get_mcp_status():
+    return {"servers": _container().mcp_service().discovery_status()}
+
+
+@app.get("/api/mcp/catalog")
+async def get_mcp_catalog():
+    return {"tools": _container().mcp_service().catalog()}
+
+
+@app.post("/api/mcp/{server_name}/connect")
+async def connect_mcp(server_name: str, payload: McpConnectMutation | None = None):
+    result = _container().mcp_service().connect(server_name, refresh=bool(payload and payload.refresh))
+    if not result.get("ok"):
+        raise HTTPException(status_code=502, detail=result.get("error") or "MCP 连接/发现失败")
+    return result
+
+
+@app.post("/api/mcp")
+async def create_mcp(payload: McpServerMutation):
+    """创建新 MCP Server。name 来自 payload.name，否则按 ts 生成。"""
+    server_name = (payload.name or "").strip() or f"mcp-{int(time.time())}"
+    try:
+        return _container().mcp_service().upsert(
+            name=server_name,
+            command=payload.command or "",
+            args=payload.args or [],
+            env=payload.env or {},
+            transport=payload.transport or "stdio",
+            url=payload.url or "",
+            description=payload.description or "",
+            enabled=payload.enabled if payload.enabled is not None else True,
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=409, detail=str(e))
+
+
+@app.put("/api/mcp/{server_name}")
+async def put_mcp(server_name: str, payload: McpServerMutation):
+    # 直接走 McpService（应用层入口）
+    return _container().mcp_service().upsert(
+        name=server_name,
+        command=payload.command or "",
+        args=payload.args or [],
+        env=payload.env or {},
+        transport=payload.transport or "stdio",
+        url=payload.url or "",
+        description=payload.description or "",
+        enabled=payload.enabled if payload.enabled is not None else True,
+    )
+
+
+@app.post("/api/mcp/{server_name}/toggle")
+async def toggle_mcp(server_name: str, payload: McpToggleMutation | None = None, enabled: bool | None = None):
+    chosen = payload.enabled if payload and payload.enabled is not None else enabled
+    if chosen is None:
+        raise HTTPException(status_code=400, detail="缺少 enabled 参数")
+    # 走 McpService（应用层入口），与 create/put 走同一事实源
+    ok = _container().mcp_service().set_enabled(server_name, bool(chosen))
+    if not ok:
+        raise HTTPException(status_code=404, detail="MCP Server 不存在")
+    return {"ok": True, "name": server_name, "enabled": bool(chosen)}
+
+
+@app.get("/api/skills/{skill_name}")
+async def get_skill_detail(skill_name: str):
+    detail = _container().skill_service().get_skill_detail(skill_name)
+    if not detail:
+        raise HTTPException(status_code=404, detail=f"Skill {skill_name} 不存在")
+    return detail
+
+
+@app.patch("/api/skills/{skill_name}")
+async def patch_skill(skill_name: str, payload: SkillPatch):
+    """更新 SKILL.md 的 frontmatter 字段（visibility / description / assigned_agents）。
+    Body 字段为空则跳过；不为空则合并到现有 frontmatter 然后回写文件。
+    """
+    updates = payload.model_dump(exclude_none=True)
+    if not updates:
+        raise HTTPException(status_code=400, detail="没有可更新的字段")
+    detail = _container().skill_service().update_frontmatter(skill_name, updates)
+    if not detail:
+        raise HTTPException(status_code=404, detail=f"Skill {skill_name} 不存在")
+    return {"ok": True, "name": skill_name, "path": detail["path"], "updated": updates}
+
+
+@app.delete("/api/mcp/{server_name}")
+async def delete_mcp(server_name: str):
+    # 走 McpService（应用层入口），与 create/put/toggle 走同一事实源
+    ok = _container().mcp_service().remove(server_name)
+    if not ok:
+        raise HTTPException(status_code=404, detail="MCP Server 不存在")
+    return {"ok": True, "name": server_name}
+
+
+@app.get("/api/commands")
+async def get_commands():
+    return {"groups": COMMAND_GROUPS}
+
+
+@app.get("/api/workers")
+async def get_workers():
+    return {"workers": _get_workers()}
+
+
+@app.post("/api/run")
+async def run_command(cmd: str = "", task: str = "", agent: str = "", session_id: str = ""):
+    if cmd == "run-agent" or task or agent:
+        agent_name = agent or "chat"
+        _validate_agent_task(agent_name, task)
+        result = await asyncio.get_event_loop().run_in_executor(
+            _AGENT_EXECUTOR, _run_agent_sync, agent_name, task, session_id)
+        return result
+    return {"output": _run_safe_command(cmd)}
+
+
+@app.post("/api/chat")
+async def chat_api(req: ChatRequest):
+    """统一聊天接口 — POST 一次完成 session 创建/复用 + 消息发送 + 结果返回。
+
+    前端不再需要自己管理 session 状态机：
+    1. 首次发送：不传 session_id，自动创建新 session
+    2. 续聊：传已有 session_id，自动加载历史+压缩后运行
+    3. 返回：{ session_id, response, usage, iterations, tool_calls, attachments_used }
+    """
+    container = _container()
+    session_service = container.session_service()
+
+    session_id = req.session_id
+    if not session_id:
+        session = session_service.create_session(req.message[:50])
+        session_id = session["session_id"]
+
+    att_ctx, att_used = _build_attachment_context(session_id)
+
+    loop = asyncio.get_event_loop()
+    payload = await loop.run_in_executor(
+        _AGENT_EXECUTOR,
+        lambda: container.orchestration_service().run_agent_with_metrics(
+            req.agent, req.message, context=att_ctx, session_id=session_id,
+            think_mode=req.think_mode, deep_search=req.deep_search,
+        ),
+    )
+
+    return {
+        "session_id": session_id,
+        "response": payload.get("result", ""),
+        "success": payload.get("success", False),
+        "usage": payload.get("usage", {}),
+        "iterations": payload.get("iterations", 0),
+        "tool_calls": payload.get("tool_calls", 0),
+        "attachments_used": att_used,
+    }
+
+
+def _run_agent_sync(agent_name: str, task: str, session_id: str = "") -> dict[str, Any]:
+    att_ctx, att_used = _build_attachment_context(session_id)
+    container = _container()
+    try:
+        payload = container.orchestration_service().run_agent_with_metrics(
+            agent_name, task, context=att_ctx, session_id=session_id
+        )
+        payload["attachments_used"] = att_used
+        return payload
+    finally:
+        if container is _HOST_CONTAINER:
+            _shutdown_host_container()
+        else:
+            container.shutdown()
+
+
+def _run_safe_command(cmd: str) -> str:
+    base = (cmd or "").strip().split(maxsplit=1)[0] if (cmd or "").strip() else ""
+    if base == "status":
+        config = _load_config()
+        return json.dumps({
+            "status": "running",
+            "default_model": config.models.default_model,
+            "agents": len(config.agents.agents),
+        }, ensure_ascii=False, indent=2)
+    if base == "models":
+        return json.dumps(_get_models(), ensure_ascii=False, indent=2)
+    if base == "tools":
+        return json.dumps(_container().tool_service().describe_tools(), ensure_ascii=False, indent=2)
+    if base == "usage":
+        return json.dumps(_get_usage(), ensure_ascii=False, indent=2)
+    if base == "cron":
+        return json.dumps(_get_cron(), ensure_ascii=False, indent=2)
+    if base == "souls":
+        return json.dumps({"souls": _get_souls(), "current": _get_current_soul()}, ensure_ascii=False, indent=2)
+    if base == "agents":
+        return json.dumps(_get_agents(), ensure_ascii=False, indent=2)
+    if base == "workers":
+        return json.dumps(_get_workers(), ensure_ascii=False, indent=2)
+    if base == "sessions":
+        return json.dumps(_get_sessions(), ensure_ascii=False, indent=2)
+    raise HTTPException(status_code=400, detail=f"不支持的命令：{base or '空命令'}")
+
+
+@app.websocket("/ws/agent")
+async def ws_agent(ws: WebSocket):
+    await ws.accept()
+    await ws.send_json({"type": "connected", "message": "🐾 LBS Agent 编排台已连接"})
+    try:
+        while True:
+            data = await ws.receive_json()
+            if data.get("type") != "run":
+                error_payload = {"type": "done", "success": False, "error": "不支持的消息类型"}
+                if "run_id" in data or "session_id" in data:
+                    error_payload.update({
+                        "run_id": str(data.get("run_id", "")),
+                        "session_id": str(data.get("session_id", "")),
+                        "result": "",
+                    })
+                await ws.send_json(error_payload)
+                continue
+            cmd = str(data.get("cmd", ""))
+            task = str(data.get("task", ""))
+            agent_name = str(data.get("agent", ""))
+            session_id = str(data.get("session_id", "")).strip()
+            if not session_id:
+                session = _container().session_service().create_session(task[:50] or "新会话")
+                session_id = str(session["session_id"])
+            run_id = str(data.get("run_id", "")).strip() or f"run-{uuid.uuid4().hex}"
+            internal_run_id = f"ws-{uuid.uuid4().hex}"
+            think_mode = bool(data.get("think_mode", False))
+            deep_search = bool(data.get("deep_search", False))
+            await ws.send_json({
+                "type": "status",
+                "run_id": run_id,
+                "session_id": session_id,
+                "cat_state": "running",
+                "capsules": {"status": "● 运行中", "iteration": "01", "worker": agent_name or "命令执行器"},
+            })
+            started = time.perf_counter()
+            try:
+                if cmd == "run-agent" or task or agent_name:
+                    selected_agent = agent_name or "chat"
+                    _validate_agent_task(selected_agent, task)
+
+                    # Inject streaming callback into the orchestrator's agent config
+                    import queue as _queue, threading as _threading
+                    chunk_q: _queue.Queue = _queue.Queue()
+                    thread_payload: dict = {}
+                    unsubscribe_event = None
+                    deadline = time.monotonic() + 300
+                    timed_out = False
+
+                    def _on_chunk(delta: str, chunk_type: str = "text"):
+                        # 只有模型正文/思考正文进入 stream_delta；CLI 进度日志（step/tool/warn 等）
+                        # 由 runtime_event/ThinkingBlock 展示，不能混进最终回答。
+                        if delta and chunk_type in ("text", "thinking"):
+                            chunk_q.put_nowait({"text": delta, "chunk_type": chunk_type})
+
+                    def _run_with_stream():
+                        nonlocal unsubscribe_event
+                        """Run agent with streaming — no orchestrator rebuild needed.
+
+                        on_chunk/think_mode/deep_search are passed directly as parameters,
+                        eliminating the monkey-patch and the orchestrator rebuild that
+                        caused race conditions between concurrent WS connections.
+                        """
+                        container = _container()
+                        # 确保 config 是最新的（reload YAML），但只在不并发时安全刷新
+                        try:
+                            container.config = _load_config()
+                        except Exception:
+                            pass
+                        # 订阅 EventBus：转发 runtime 事件到 WebSocket 的 chunk_q
+                        # 注意：build_orchestrator 返回缓存的实例，不会重建。
+                        # 每次订阅独立的 callback，不互相干扰。
+                        try:
+                            orch = container.build_orchestrator()
+                            # 同步最新 config 到 orchestrator（确保用最新 YAML）
+                            orch.app_config = container.config
+                            def _on_event(event):
+                                chunk_q.put_nowait({
+                                    "event": event.to_dict(),
+                                })
+                            unsubscribe_event = orch.event_bus.subscribe(_on_event, run_id=internal_run_id)
+                        except Exception:
+                            pass
+
+                        att_ctx, att_used = _build_attachment_context(session_id)
+                        try:
+                            payload = container.orchestration_service().run_agent_with_metrics(
+                                selected_agent, task, context=att_ctx, session_id=session_id,
+                                run_id=internal_run_id, on_chunk=_on_chunk, think_mode=think_mode, deep_search=deep_search,
+                            )
+                            payload["attachments_used"] = att_used
+                            thread_payload["payload"] = payload
+                            return payload
+                        except Exception as e:
+                            thread_payload["error"] = str(e)
+                        finally:
+                            if unsubscribe_event is not None:
+                                unsubscribe_event()
+                            chunk_q.put_nowait(None)
+
+                    # Run in thread
+                    thread = _threading.Thread(target=_run_with_stream, daemon=True)
+                    thread.start()
+
+                    # Forward stream deltas + runtime events to WS
+                    while True:
+                        if time.monotonic() >= deadline:
+                            timed_out = True
+                            break
+                        try:
+                            item = chunk_q.get(timeout=0.1)
+                        except _queue.Empty:
+                            if not thread.is_alive():
+                                break
+                            continue
+                        if item is None:
+                            break
+                        # 区分流式文本 chunk 和 runtime 事件
+                        if "event" in item:
+                            evt = item["event"]
+                            await ws.send_json({
+                                "type": "runtime_event",
+                                "run_id": run_id,
+                                "session_id": session_id,
+                                "event_type": evt.get("type", ""),
+                                "source": evt.get("source", ""),
+                                "payload": evt.get("payload", {}),
+                            })
+                        else:
+                            await ws.send_json({
+                                "type": "stream_delta",
+                                "run_id": run_id,
+                                "session_id": session_id,
+                                "text": item.get("text", ""),
+                                "chunk_type": item.get("chunk_type", "text"),
+                            })
+
+                    thread.join(timeout=0.1)
+                    if timed_out:
+                        # 超时后确保线程不再持有 EventBus 订阅和 chunk_q
+                        if unsubscribe_event is not None:
+                            try: unsubscribe_event()
+                            except: pass
+                        # 置为 daemon，让它在后台自然结束，不阻塞 API 线程池
+                        payload = {"result": "", "error": "Agent 执行超时", "success": False}
+                    else:
+                        # Get result from the thread
+                        payload = thread_payload.get("payload") or {"result": "", "error": thread_payload.get("error", "未知错误"), "success": False}
+                    output = payload.get("result", "") or payload.get("error", "")
+                    success = bool(payload.get("success", False))
+                else:
+                    payload = None
+                    output = _run_safe_command(cmd)
+                    success = True
+                    await ws.send_json({
+                        "type": "step",
+                        "run_id": run_id,
+                        "session_id": session_id,
+                        "text": f"命令 {cmd or '空'} 已执行",
+                    })
+                # 持久化消息到 session（含 model/usage/context 供历史会话显示）
+                usage = payload.get("usage", {}) if isinstance(payload, dict) else {}
+                _container().session_service().append_interaction(
+                    session_id,
+                    agent_name=agent_name or "chat",
+                    task=task,
+                    output=output,
+                    success=success,
+                    model=(payload.get("model", "") if isinstance(payload, dict) else ""),
+                    usage=({"input": usage.get("input", 0), "output": usage.get("output", 0), "cost": usage.get("cost", "0")} if usage else None),
+                    context_info=(payload.get("context", {}) if isinstance(payload, dict) else None),
+                    iterations=payload.get("iterations", 0) if isinstance(payload, dict) else 0,
+                    total_tool_calls=payload.get("tool_calls", 0) if isinstance(payload, dict) else 0,
+                    duration_seconds=payload.get("duration_seconds", 0) if isinstance(payload, dict) else 0,
+                )
+                await ws.send_json({"type": "output", "run_id": run_id, "session_id": session_id, "text": output, "streaming": False})
+                await ws.send_json({
+                    "type": "done", "run_id": run_id, "session_id": session_id, "success": success, "result": output,
+                    "error": "" if success else output,
+                    "duration_seconds": round(time.perf_counter() - started, 3),
+                    "cat_state": "success" if success else "error",
+                    "model": (payload.get("model", "") if isinstance(payload, dict) else ""),
+                    "usage": {"input": usage.get("input", 0), "output": usage.get("output", 0), "cost": usage.get("cost", "0")},
+                    "context": (payload.get("context", {}) if isinstance(payload, dict) else {}),
+                    "iterations": (payload.get("iterations", 0) if isinstance(payload, dict) else 0),
+                    "tool_calls": (payload.get("tool_calls", 0) if isinstance(payload, dict) else 0),
+                    "attachments_used": (payload.get("attachments_used", []) if isinstance(payload, dict) else []),
+                })
+            except Exception as exc:
+                _container().session_service().append_interaction(
+                    session_id, agent_name=agent_name or "chat", task=task, output=str(exc), success=False
+                )
+                await ws.send_json({
+                    "type": "done", "run_id": run_id, "session_id": session_id, "success": False, "error": str(exc),
+                    "duration_seconds": round(time.perf_counter() - started, 3),
+                    "cat_state": "error",
+                })
+    except WebSocketDisconnect:
+        return
+
+dist_dir = FRONTEND_DIST
+if dist_dir.is_dir():
+    app.mount("/", StaticFiles(directory=str(dist_dir), html=True), name="static")
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8199)