feat(v3): T17-T18 模型池 + 工具智能体后端

- T17 模型池：PoolStore（local/budget/premium 条目 + architect/worker/agent 角色指派），
  /pool CRUD+连通测试+模型探测端点；build_v2_pipeline 池指派优先（测试 override 最后）；
  V2Stats 新增 by_model 按 token/成本分账
- T18 智能体：OpenAI 兼容工具调用客户端（transport 可注入）+ AgentService
  （事件落盘 agent_runs/{id}/events.jsonl）+ /agent 提交/status/events/SSE stream
  + 工作区浏览/读取端点（越界 400）；轮数与 token 双护栏，模型经池 agent 角色或经典回退
- 新增测试 16 项，全量 262 passed（httpx 假注入，不依赖真实模型/key）

gateway/api.py

@@ -12,6 +12,16 @@ v2 端点（《实现方案_v2》5.3）：
 """
 from __future__ import annotations
 
+import os as _os
+from pathlib import Path as _Path
+
+# 加载项目根目录的 .env 文件（包含 DEEPSEEK_API_KEY 等密钥）
+_dotenv_path = _Path(__file__).resolve().parent.parent / ".env"
+if _dotenv_path.exists():
+    from dotenv import load_dotenv
+    load_dotenv(_dotenv_path)
+
+import asyncio
 from pathlib import Path
 from typing import List, Optional
 
@@ -20,6 +30,14 @@ from pydantic import BaseModel, Field
 from router_system.config import load_config
 from router_system.router import Router, build_router
 
+from gateway.jobs import get_job_store, JobStore
+from gateway.model_pool import (
+    compute_cost,
+    entry_to_architect_cfg,
+    entry_to_worker_cfg,
+    get_pool,
+)
+
 # ---- v2 依赖（惰性导入，缺依赖时降级提示） ----
 try:
     from router_system.architect import build_architect
@@ -84,14 +102,22 @@ def build_v2_pipeline(worker_cfg_override: Optional[dict] = None):
         s = settings_store().to_dict() if _V2_OK else {}
         kb = KnowledgeBase()
 
-        # architect（合并用户设置）
+        # architect（合并用户设置；模型池指派优先——多价位模型，D1）
         acfg = dict(cfg.get("architect", {}))
         acfg.update(s.get("architect", {}))
+        pool = get_pool()
+        pe = pool.resolve("architect")
+        if pe is not None:
+            acfg.update(entry_to_architect_cfg(pe))
         architect = build_architect(acfg)
 
-        # worker（合并用户设置；backend 可 mock/openai/llama_server）
+        # worker（合并用户设置；backend 可 mock/openai/llama_server；
+        # 模型池指派优先，测试注入 override 最后生效）
         wcfg = dict(cfg.get("worker", {}))
         wcfg.update(s.get("worker", {}))
+        pw = pool.resolve("worker")
+        if pw is not None:
+            wcfg.update(entry_to_worker_cfg(pw))
         if worker_cfg_override:
             wcfg.update(worker_cfg_override)
         worker = build_worker(wcfg, kb=kb)
@@ -124,6 +150,10 @@ class QueryRequest(BaseModel):
     domain_group: Optional[str] = Field(
         None, description="大领域组（两级路由第一级）：tech | professional | lifestyle | general；不指定则自动检测"
     )
+    mode: str = Field(
+        "fast",
+        description="执行模式：fast（快路径，小模型直答优先）| full（完整协作，DeepSeek 架构师全程参与）"
+    )
 
 
 class HealthResponse(BaseModel):
@@ -137,9 +167,11 @@ class HealthResponse(BaseModel):
 # ---- FastAPI 应用 ----
 try:
     from fastapi import FastAPI, HTTPException
+    from fastapi.staticfiles import StaticFiles
     from fastapi.responses import HTMLResponse
 
     _INDEX_PATH = Path(__file__).resolve().parent / "static" / "index.html"
+    _STATIC_DIR = Path(__file__).resolve().parent / "static"
 
     app = FastAPI(
         title="端云协同 LLM 协作系统",
@@ -147,44 +179,151 @@ try:
         version="2.0.0",
     )
 
+    # Vue SPA 静态资源（html=True：对不存在的路径 fallback 到 index.html，支持 SPA 路由）
+    app.mount("/static", StaticFiles(directory=str(_STATIC_DIR), html=True), name="static")
+
+    @app.get("/", response_class=HTMLResponse, tags=["ui"])
+    async def index():
+        """Vue SPA 的 index.html（FastAPI API 路由优先，此处仅作 fallback）。"""
+        if _INDEX_PATH.exists():
+            return HTMLResponse(_INDEX_PATH.read_text(encoding="utf-8"))
+        return HTMLResponse("<h1>端云协同 LLM 系统</h1><p>请先构建前端：cd webapp && npm run build</p>")
+
     @app.get("/health", response_model=HealthResponse, tags=["system"])
     async def health():
         return get_router().health()
 
-    @app.get("/", response_class=HTMLResponse, tags=["ui"])
-    async def index():
-        """端云协同 Web 界面（单文件前端，无需构建）。"""
-        if _INDEX_PATH.exists():
-            return HTMLResponse(_INDEX_PATH.read_text(encoding="utf-8"))
-        return HTMLResponse("<h1>Web 界面未生成</h1><p>缺少 gateway/static/index.html</p>")
-
-    # ---------------- v2：/chat ----------------
+    # Vue SPA（由 StaticFiles mount 在 / 路径提供）
     @app.post("/chat", tags=["chat"])
     async def chat(req: QueryRequest):
-        try:
-            result = await get_pipeline().run(req.query)
-        except ValueError as e:
-            raise HTTPException(status_code=400, detail=str(e))
-        # 记账 + 入队
-        if _v2stats is not None:
-            _v2stats.record(result)
-        _maybe_enqueue(result)
+        """立即返回 request_id，协作管线在后台 asyncio.Task 中运行。
+
+        完成后结果写入 runs/{id}/workspace.json（由 pipeline 内部完成），
+        状态通过 GET /runs/{id}/status 查询，SSE 通过 /runs/{id}/stream 订阅。
+        """
+        import uuid
+
+        request_id = uuid.uuid4().hex[:12]
+        run_dir = Path("runs") / request_id
+        run_dir.mkdir(parents=True, exist_ok=True)
+
+        # 注册任务（容量满时拒绝）
+        ok, msg = get_job_store().register(request_id)
+        if not ok:
+            raise HTTPException(status_code=503, detail=msg)
+
+        # 提交后台协程
+        async def _run():
+            job_store = get_job_store()
+            try:
+                pipeline = get_pipeline()
+                # mode=full 时临时跳过快路径，直接走架构师协作（DeepSeek V4）
+                if req.mode == "full":
+                    old_fast = pipeline.fast_path
+                    pipeline.fast_path = False
+                    try:
+                        result = await pipeline.run(req.query, request_id=request_id)
+                    finally:
+                        pipeline.fast_path = old_fast
+                else:
+                    result = await pipeline.run(req.query, request_id=request_id)
+                if _v2stats is not None:
+                    # 按模型池单价分账（条目未命中时 cost_est 保持管线原值）
+                    entry = get_pool().find_by_model(result.model_used or "")
+                    if entry is not None:
+                        result.cost_est = compute_cost(
+                            entry, result.api_input_tokens, result.api_output_tokens)
+                    _v2stats.record(result)
+                _maybe_enqueue(result)
+                job_store._task_done(request_id, result)
+            except Exception as exc:
+                import traceback
+                traceback.print_exc()
+                job_store._task_failed(request_id, "pipeline_error", detail=str(exc))
+                # 写一份失败状态到 workspace.json（pipeline 异常时）
+                try:
+                    import json
+                    fail_ws = {
+                        "request_id": request_id,
+                        "query": req.query,
+                        "status": "failed",
+                        "error": str(exc),
+                        "brief": None, "plan": [], "progress": [],
+                        "issues": [], "decisions": [], "archive": [],
+                        "meta": {"state": "failed", "round": 0, "rounds_cap": 6,
+                                 "api_input_tokens": 0, "api_output_tokens": 0},
+                    }
+                    (run_dir / "workspace.json").write_text(
+                        json.dumps(fail_ws, ensure_ascii=False, indent=2), encoding="utf-8")
+                except Exception:
+                    pass
+
+        get_job_store().submit(request_id, _run())
+        return {"request_id": request_id, "status": "pending"}
+
+    # ---------------- v2：任务状态 ----------------
+    @app.get("/runs/{request_id}/status", tags=["v2"])
+    async def get_run_status(request_id: str):
+        """查询任务当前状态（pending / running / done / failed）。"""
+        info = get_job_store().get(request_id)
+        if info is None:
+            raise HTTPException(status_code=404, detail=f"任务 {request_id} 不存在")
+        ws_state = None
+        ws_path = Path("runs") / request_id / "workspace.json"
+        if ws_path.exists():
+            import json
+            try:
+                ws_data = json.loads(ws_path.read_text(encoding="utf-8"))
+                ws_state = ws_data.get("meta", {}).get("state") or ws_data.get("status")
+            except Exception:
+                ws_state = "done"
         return {
-            "response": result.response,
-            "request_id": result.request_id,
-            "status": result.status,
-            "fast_path": result.fast_path,
-            "rounds_used": result.rounds_used,
-            "api_input_tokens": result.api_input_tokens,
-            "api_output_tokens": result.api_output_tokens,
-            "cost_est": result.cost_est,
-            "model_used": result.model_used,
-            "latency_ms": round(result.latency_ms, 2),
-            "route": result.route,
-            "workspace_path": result.workspace_path,
-            "error": result.error,
+            "request_id": request_id,
+            "status": info.state,       # pending | running | done | failed
+            "ws_state": ws_state,
+            "started_at": info.started_at,
+            "finished_at": info.finished_at,
+            "error": info.error,
+            # PipelineResult 等效字段（扁平存储在 TaskInfo 中）
+            "response": info.response,
+            "pipeline_status": info.status,
+            "fast_path": info.fast_path,
+            "rounds_used": info.rounds_used,
+            "api_input_tokens": info.api_input_tokens,
+            "api_output_tokens": info.api_output_tokens,
+            "cost_est": info.cost_est,
+            "model_used": info.model_used,
+            "latency_ms": round(info.latency_ms, 2) if info.latency_ms else None,
+            "route": info.route,
+            "workspace_path": info.workspace_path,
         }
 
+    # ---------------- v2：SSE 实时流 ----------------
+    @app.get("/runs/{request_id}/stream", tags=["v2"])
+    async def stream_run(request_id: str):
+        """SSE 端点：实时推送 workspace.json 状态变化（供前端协作可视化）。"""
+        from fastapi.responses import StreamingResponse
+
+        async def event_generator():
+            import json  # noqa: F401
+            cancel_event = get_job_store().new_cancel(request_id)
+            try:
+                async for ev in get_job_store().watch_workspace(request_id, cancel_event):
+                    payload = json.dumps(ev, ensure_ascii=False)
+                    yield f"data: {payload}\n\n"
+            finally:
+                cancel_event.set()
+
+        return StreamingResponse(
+            event_generator(),
+            media_type="text/event-stream",
+            headers={
+                "Cache-Control": "no-cache",
+                "Connection": "keep-alive",
+                "X-Accel-Buffering": "no",
+            },
+        )
+
     # ---------------- v1：/chat/legacy ----------------
     @app.post("/chat/legacy", tags=["chat"])
     async def chat_legacy(req: QueryRequest):
@@ -251,6 +390,225 @@ try:
             raise HTTPException(status_code=404, detail=f"审核记录不存在或已审核: {review_id}")
         return {"ok": True, "review_id": review_id, "verdict": verdict}
 
+    # ---------------- 模型池（多价位异构模型） ----------------
+    @app.get("/pool", tags=["pool"])
+    async def pool_list():
+        """读取模型池（角色指派 + 条目列表，api_key 打码）。"""
+        return get_pool().list()
+
+    @app.post("/pool", tags=["pool"])
+    async def pool_upsert(entry: dict):
+        """新增或更新池条目（按 id）。api_key 留空表示保留原值。"""
+        try:
+            get_pool().upsert(entry)
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=f"条目非法: {e}")
+        rebuild_pipeline()
+        return get_pool().list()
+
+    @app.delete("/pool/{entry_id}", tags=["pool"])
+    async def pool_delete(entry_id: str):
+        ok = get_pool().delete(entry_id)
+        if ok:
+            rebuild_pipeline()
+        return {"ok": ok, **get_pool().list()}
+
+    @app.put("/pool/roles", tags=["pool"])
+    async def pool_roles(roles: dict):
+        """指派角色：{"architect": "<id|>", "worker": "<id|>", "agent": "<id|>"}。
+        空串 = 沿用经典单模型设置。"""
+        try:
+            get_pool().set_roles(roles)
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=f"指派非法: {e}")
+        rebuild_pipeline()
+        return get_pool().list()
+
+    @app.post("/pool/{entry_id}/test", tags=["pool"])
+    async def pool_test(entry_id: str):
+        """连通性测试：用条目自身的端点/凭据探测 /models。"""
+        entry = get_pool().get(entry_id)
+        if entry is None:
+            raise HTTPException(status_code=404, detail=f"条目不存在: {entry_id}")
+        if entry["backend"] == "mock":
+            return {"ok": True, "detail": "mock 后端无需测试"}
+        r = await _probe_backend(entry["backend"], entry["base_url"], entry.get("api_key", ""))
+        return r
+
+    @app.get("/pool/{entry_id}/models", tags=["pool"])
+    async def pool_models(entry_id: str):
+        """探测该条目端点下的可用模型列表。"""
+        entry = get_pool().get(entry_id)
+        if entry is None:
+            raise HTTPException(status_code=404, detail=f"条目不存在: {entry_id}")
+        if entry["backend"] == "mock":
+            return {"models": [{"id": "mock", "name": "mock（内置模拟）"}]}
+        return await _list_backend_models(
+            entry["backend"], entry["base_url"], entry.get("api_key", ""))
+
+    # ---------------- 智能体（工具调用，zcode 式文件操作） ----------------
+    def _resolve_agent_chat(pool_id: str = ""):
+        """解析智能体模型：显式 pool_id > 池 agent 角色 > 经典 Architect 设置。
+
+        返回 (OpenAICompatChat, model_name, pool_id)；无法解析时抛 HTTPException。
+        """
+        from gateway.agent import OpenAICompatChat
+
+        pool = get_pool()
+        entry = pool.get(pool_id) if pool_id else pool.resolve("agent")
+        if entry is not None:
+            if entry["backend"] == "llama_server" and not entry.get("api_key"):
+                chat = OpenAICompatChat(
+                    base_url=entry["base_url"] or "http://127.0.0.1:8901/v1",
+                    api_key=None, model=entry["model"],
+                    temperature=float(entry.get("temperature", 0.3)),
+                    max_tokens=int(entry.get("max_tokens", 4096)))
+            elif entry["backend"] == "mock":
+                raise HTTPException(status_code=400,
+                                    detail="mock 模型不支持智能体工具调用，请选择真实模型")
+            else:
+                chat = OpenAICompatChat(
+                    base_url=entry["base_url"], api_key=entry.get("api_key") or None,
+                    model=entry["model"],
+                    temperature=float(entry.get("temperature", 0.3)),
+                    max_tokens=int(entry.get("max_tokens", 4096)))
+            return chat, entry["model"], entry["id"]
+        # 经典回退：Architect 设置（api_key 走 .env）
+        import os
+        s = settings_store().to_dict()
+        acfg = dict(load_config().get("architect", {}))
+        acfg.update(s.get("architect", {}))
+        key = acfg.get("api_key") or os.environ.get(acfg.get("api_key_env", "DEEPSEEK_API_KEY"))
+        if not key:
+            raise HTTPException(
+                status_code=400,
+                detail="未配置大模型 API Key：请在模型池指派 agent 角色（填 key），或在设置中配置 Architect API Key")
+        chat = build_agent_chat(acfg)
+        return chat, acfg.get("model", "unknown"), ""
+
+    def build_agent_chat(acfg: dict):
+        """经典设置 -> OpenAICompatChat（独立函数便于测试注入替身）。"""
+        from gateway.agent import OpenAICompatChat
+        import os
+        key = acfg.get("api_key") or os.environ.get(acfg.get("api_key_env", "DEEPSEEK_API_KEY"))
+        return OpenAICompatChat(
+            base_url=acfg.get("base_url", "https://api.deepseek.com"),
+            api_key=key,
+            model=acfg.get("model", "deepseek-v4-flash"),
+            temperature=float(acfg.get("temperature", 0.2)),
+            max_tokens=int(acfg.get("max_tokens", 4096)),
+        )
+
+    @app.post("/agent", tags=["agent"])
+    async def agent_run(req: dict):
+        """提交智能体任务：{"task": "...", "pool_id": "可选模型条目"}。
+
+        立即返回 request_id；过程事件经 GET /agent/{id}/stream (SSE) 推送。
+        """
+        from gateway.agent import get_agent_service, new_request_id
+
+        task = str((req or {}).get("task") or "").strip()
+        if not task:
+            raise HTTPException(status_code=400, detail="task 不能为空")
+        if len(task) > 8000:
+            raise HTTPException(status_code=400, detail="task 过长（>8000）")
+        pool_id = str((req or {}).get("pool_id") or "")
+
+        chat, model, used_pool_id = _resolve_agent_chat(pool_id)
+        service = get_agent_service()
+        request_id = new_request_id()
+        info = service.register(request_id, task, model, used_pool_id)
+        if info is None:
+            raise HTTPException(status_code=503, detail="智能体同时运行任务已达上限")
+
+        s = settings_store().to_dict()
+        agent_cfg = s.get("agent", {})
+
+        async def _run():
+            try:
+                await service.run(
+                    info, chat,
+                    workspace_dir=agent_cfg.get("workspace_dir", "agent_workspace"),
+                    max_rounds=int(agent_cfg.get("max_rounds", 8)),
+                    token_cap=int(agent_cfg.get("token_cap", 20000)),
+                )
+            except Exception as exc:
+                import traceback
+                traceback.print_exc()
+                info.state = "failed"
+                info.error = str(exc)
+                info.finished_at = __import__("time").time()
+                service._write_status(info)
+
+        info.asyncio_task = asyncio.create_task(_run())
+        return {"request_id": request_id, "status": "running", "model": model}
+
+    @app.get("/agent/{request_id}/status", tags=["agent"])
+    async def agent_status(request_id: str):
+        from gateway.agent import get_agent_service
+        info = get_agent_service().get(request_id)
+        if info is None:
+            # 尝试磁盘恢复（服务重启后仍可查历史）
+            p = get_agent_service().status_path(request_id)
+            if p.exists():
+                import json
+                return json.loads(p.read_text(encoding="utf-8"))
+            raise HTTPException(status_code=404, detail=f"智能体任务不存在: {request_id}")
+        return info.to_dict()
+
+    @app.get("/agent/{request_id}/events", tags=["agent"])
+    async def agent_events(request_id: str):
+        """完整事件列表（JSON，刷新后恢复用）。"""
+        from gateway.agent import get_agent_service
+        return get_agent_service().read_events(request_id)
+
+    @app.get("/agent/{request_id}/stream", tags=["agent"])
+    async def agent_stream(request_id: str):
+        """SSE：实时推送智能体过程事件（round/tool_call/tool_result/usage/final）。"""
+        from fastapi.responses import StreamingResponse
+        from gateway.agent import get_agent_service
+
+        async def event_generator():
+            import json
+            cancel = asyncio.Event()
+            try:
+                async for ev in get_agent_service().watch_events(request_id, cancel):
+                    yield f"data: {json.dumps(ev, ensure_ascii=False)}\n\n"
+            finally:
+                cancel.set()
+
+        return StreamingResponse(
+            event_generator(),
+            media_type="text/event-stream",
+            headers={"Cache-Control": "no-cache", "Connection": "keep-alive",
+                     "X-Accel-Buffering": "no"},
+        )
+
+    @app.get("/agent/workspace", tags=["agent"])
+    async def agent_workspace(path: str = ""):
+        """列出智能体工作区（默认根目录；path 指定子目录）。越界返回 400。"""
+        from router_system.tools import ToolError, WorkspaceTools
+        s = settings_store().to_dict()
+        tools = WorkspaceTools(s.get("agent", {}).get("workspace_dir", "agent_workspace"))
+        try:
+            return tools.list_dir(path)
+        except ToolError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+
+    @app.get("/agent/file", tags=["agent"])
+    async def agent_file(path: str):
+        """读取智能体工作区内文件（前端预览，越界即 400）。"""
+        from router_system.tools import ToolError, WorkspaceTools
+        s = settings_store().to_dict()
+        tools = WorkspaceTools(s.get("agent", {}).get("workspace_dir", "agent_workspace"))
+        try:
+            result = tools.read_file(path)
+        except ToolError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+        if not result.get("ok"):
+            raise HTTPException(status_code=404, detail=result.get("error", "读取失败"))
+        return result
+
     # ---------------- 模型设置（用户可调整） ----------------
     @app.get("/config", tags=["settings"])
     async def get_config():
@@ -276,8 +634,238 @@ try:
         rebuild_pipeline()
         return merged
 
-    # ---------------- metrics ----------------
-    @app.get("/metrics", tags=["system"])
+    # ---------------- 模型发现 & 验证（/config 与 /pool 共用） ----------------
+    async def _list_backend_models(backend: str, base_url: str = "", api_key: str = "") -> dict:
+        """探测 OpenAI 兼容端点的模型列表。返回 {"models":[...]} 或 {"error": "..."}。"""
+        import httpx
+
+        if backend == "llama_server":
+            url = (base_url or f"http://127.0.0.1:{settings_store().get('worker','port',8901)}/v1") + "/models"
+        elif backend == "openai":
+            if not base_url:
+                return {"error": "openai 后端需要填写 API 地址"}
+            url = base_url.rstrip("/") + "/models"
+        else:
+            return {"error": f"不支持的后端类型: {backend}"}
+
+        headers = {}
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+
+        try:
+            async with httpx.AsyncClient(timeout=10.0) as client:
+                resp = await client.get(url, headers=headers)
+                resp.raise_for_status()
+                data = resp.json()
+                models = []
+                # OpenAI /models 格式：{"object": "list", "data": [{"id": "..."}]}
+                # Ollama /models 格式：{"models": [{"name": "..."}]}
+                raw = data.get("data") or data.get("models") or []
+                for m in raw:
+                    mid = m.get("id") or m.get("name") or ""
+                    if mid:
+                        models.append({"id": mid, "name": mid})
+                return {"models": models}
+        except httpx.TimeoutException:
+            return {"error": "连接超时，模型服务可能未启动"}
+        except httpx.HTTPStatusError as e:
+            return {"error": f"HTTP {e.response.status_code}：{e.response.text[:200]}"}
+        except Exception as e:
+            return {"error": str(e)}
+
+    async def _probe_backend(backend: str, base_url: str = "", api_key: str = "") -> dict:
+        """后端连通性探测。返回 {"ok": bool, ...}。"""
+        import httpx
+
+        if backend == "llama_server":
+            url = (base_url or f"http://127.0.0.1:{settings_store().get('worker','port',8901)}/v1") + "/models"
+        elif backend == "openai":
+            if not base_url:
+                return {"ok": False, "detail": "openai 后端需要填写 API 地址"}
+            url = base_url.rstrip("/") + "/models"
+        else:
+            return {"ok": False, "detail": f"不支持的后端: {backend}"}
+
+        headers = {}
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+
+        try:
+            async with httpx.AsyncClient(timeout=10.0) as client:
+                resp = await client.get(url, headers=headers)
+                resp.raise_for_status()
+                return {"ok": True, "status_code": resp.status_code}
+        except Exception as e:
+            return {"ok": False, "detail": str(e)}
+
+    @app.get("/config/models", tags=["settings"])
+    async def list_models(backend: str, base_url: str = "", api_key: str = ""):
+        """探测指定后端支持的模型列表。
+
+        backend: llama_server | openai
+        base_url: 端点地址（llama_server 默认 http://127.0.0.1:8901/v1）
+        api_key: 可选（云端 API 需要）
+
+        返回 {"models": [{"id": "...", "name": "..."}]}
+        """
+        return await _list_backend_models(backend, base_url, api_key)
+
+    @app.get("/config/ping", tags=["settings"])
+    async def ping_backend(backend: str, base_url: str = "", api_key: str = ""):
+        """验证后端连接是否可用（健康检查）。"""
+        return await _probe_backend(backend, base_url, api_key)
+
+    # ─────────────────────────────────────────────────────────────────────
+    # llama-server 内置管理
+    # ─────────────────────────────────────────────────────────────────────
+    from gateway.llama_manager import get_llama_manager
+
+    @app.get("/llama/status", tags=["llama"])
+    async def llama_status():
+        """查询 llama-server 运行状态。"""
+        lm = get_llama_manager()
+        s = lm.status()
+        return {
+            "running": s.running,
+            "pid": s.pid,
+            "model": s.model,
+            "port": s.port,
+            "base_url": s.base_url,
+            "started_at": s.started_at,
+            "error": s.error,
+        }
+
+    @app.get("/llama/models", tags=["llama"])
+    async def llama_local_models():
+        """列出本地已有模型文件（models/*.gguf）。"""
+        lm = get_llama_manager()
+        return {"models": lm.list_local_models()}
+
+    @app.post("/llama/start", tags=["llama"])
+    async def llama_start(
+        model: str,
+        port: int = 8901,
+        ngl: int = 99,
+        ctx: int = 4096,
+    ):
+        """启动本地 llama-server。
+
+        model: 模型文件路径（相对于项目根，或绝对路径）
+        port/ngl/ctx: 服务参数
+        """
+        lm = get_llama_manager()
+        s = await lm.start(model=model, port=port, ngl=ngl, ctx=ctx)
+        return {
+            "running": s.running,
+            "pid": s.pid,
+            "model": s.model,
+            "port": s.port,
+            "base_url": s.base_url,
+            "error": s.error,
+        }
+
+    @app.post("/llama/stop", tags=["llama"])
+    async def llama_stop():
+        """停止本地 llama-server。"""
+        lm = get_llama_manager()
+        await lm.stop()
+        return {"running": False}
+
+    @app.post("/llama/download", tags=["llama"])
+    async def llama_download(
+        url: str,
+        dest: Optional[str] = None,
+    ):
+        """从 HuggingFace 或直链下载 .gguf 模型到 models/ 目录。
+
+        支持 HuggingFace 路径别名，如 "Qwen/Qwen3-4B-GGUF/Qwen3-4B-Q4_K_M.gguf"
+        """
+        lm = get_llama_manager()
+        # 检查是否已在下载
+        existing = lm.get_download_progress(url)
+        if existing and not existing.done:
+            return {
+                "url": url,
+                "dest": existing.dest,
+                "downloaded_bytes": existing.downloaded_bytes,
+                "total_bytes": existing.total_bytes,
+                "progress_pct": existing.progress_pct,
+                "speed": existing.speed,
+                "eta": existing.eta,
+                "done": False,
+                "error": None,
+            }
+        prog = await lm.download_model(url=url, dest=dest)
+        return {
+            "url": prog.url,
+            "dest": prog.dest,
+            "downloaded_bytes": prog.downloaded_bytes,
+            "total_bytes": prog.total_bytes,
+            "progress_pct": prog.progress_pct,
+            "speed": prog.speed,
+            "eta": prog.eta,
+            "done": prog.done,
+            "error": prog.error,
+        }
+
+    @app.get("/llama/download/stream", tags=["llama"])
+    async def llama_download_progress(url: str):
+        """SSE：推送模型下载进度。"""
+        from fastapi.responses import StreamingResponse
+
+        async def event_gen():
+            lm = get_llama_manager()
+            last_pct = -1.0
+            while True:
+                prog = lm.get_download_progress(url)
+                if prog and (prog.done or abs(prog.progress_pct - last_pct) > 0.1):
+                    payload = json.dumps({
+                        "url": prog.url,
+                        "dest": prog.dest,
+                        "downloaded_bytes": prog.downloaded_bytes,
+                        "total_bytes": prog.total_bytes,
+                        "progress_pct": round(prog.progress_pct, 2),
+                        "speed": prog.speed,
+                        "eta": prog.eta,
+                        "done": prog.done,
+                        "error": prog.error,
+                    }, ensure_ascii=False)
+                    yield f"data: {payload}\n\n"
+                    last_pct = prog.progress_pct
+                if prog and prog.done:
+                    break
+                await asyncio.sleep(0.5)
+
+        return StreamingResponse(
+            event_gen(),
+            media_type="text/event-stream",
+            headers={"Cache-Control": "no-cache", "Connection": "keep-alive",
+                     "X-Accel-Buffering": "no"},
+        )
+
+    # ─────────────────────────────────────────────────────────────────
+    # Vue SPA 页面路由（非 API，交给前端 Vue Router 处理）
+    # 这些路径返回 index.html，浏览器加载后由 Vue Router 渲染对应页面
+    # ─────────────────────────────────────────────────────────────────
+    @app.get("/", include_in_schema=False)
+    @app.get("/chat", include_in_schema=False)
+    @app.get("/collaboration", include_in_schema=False)
+    @app.get("/review", include_in_schema=False)
+    @app.get("/settings", include_in_schema=False)
+    @app.get("/agent", include_in_schema=False)
+    async def spa_page():
+        """所有前端页面路径返回 Vue SPA index.html。"""
+        if _INDEX_PATH.exists():
+            return HTMLResponse(_INDEX_PATH.read_text(encoding="utf-8"))
+        return HTMLResponse("<h1>端云协同 LLM 系统</h1><p>请构建前端：cd webapp && npm run build</p>")
+
+    # ---------------- metrics API（JSON REST 端点）--------------------
+    # 前端通过 axios GET /api/metrics 调用此端点获取指标数据
+    @app.get("/metrics", include_in_schema=False)
+    async def metrics_page():
+        return await metrics()
+
+    @app.get("/api/metrics", tags=["system"])
     async def metrics():
         out = {
             "router": get_router().stats.summary(),