""" Heicode P5 — Manager 侧 /api/agnet/* 本地 stub 完全按 heicode 仓库 docs/integration/agnet-platform-request-contract.md 的字段形态返回 mock 数据， 便于 cc-haha 客户端 / heicode web 前端在 agent-manager 真正落地前先联调主流程。 存储：内存 dict，重启清空。不调真实 K8s。 鉴权：复用 require_auth（与已上线 4 个登录接口同一机制）。 真实 Agnet 平台落地后，把内部 _store + 假数据生成切换成 outbound HTTP client 即可， 对前端 0 改动（路径 / 字段 / 错误码完全相同）。 12 个端点： 1. POST /api/agnet/deployments 2. GET /api/agnet/deployments 3. GET /api/agnet/deployments/{id} 4. POST /api/agnet/deployments/{id}/stop 5. GET /api/agnet/deployments/{id}/logs 6. GET /api/agnet/deployments/{id}/logs/stream (SSE) 7. GET /api/agnet/projects/{binding_scope}/dashboard-snapshot 8. GET /api/agnet/deployments/{id}/metrics 9. GET /api/agnet/deployments/{id}/events 10. GET /api/agnet/audit-logs 11. POST /api/agnet/sk-snapshots/resolve 12. GET /api/agnet/deployments/{id}/sk-snapshots """ from __future__ import annotations import asyncio import json import secrets import time import uuid from datetime import datetime, timedelta from typing import Any, Dict, List, Optional from fastapi import APIRouter, Depends, HTTPException, Query, Request, status from fastapi.responses import StreamingResponse from app.auth import require_auth from app.routes.resources import reject_sensitive_keys from app.schemas import SuccessResponse router = APIRouter(prefix="/api/agnet", tags=["Heicode P5 Agnet Stub"]) # ==================== 内存 store ==================== class _AgnetStubStore: """内存存储所有 stub 数据。多副本部署下每副本独立，仅供联调。""" def __init__(self): self.deployments: Dict[str, Dict[str, Any]] = {} self.events: Dict[str, List[Dict[str, Any]]] = {} # deployment_id → events self.logs: Dict[str, List[Dict[str, Any]]] = {} # deployment_id → logs self.sk_snapshots: Dict[str, List[Dict[str, Any]]] = {} # deployment_id → snapshots self.audit_logs: List[Dict[str, Any]] = [] self.idempotency_cache: Dict[str, Dict[str, Any]] = {} # idempotency_key → response self.lock = asyncio.Lock() _store = _AgnetStubStore() def _now_iso() -> str: return datetime.utcnow().isoformat(timespec="microseconds") + "Z" def _new_id(prefix: str) -> str: return f"{prefix}_{secrets.token_hex(6)}" def _correlation_id(request: Request, fallback_field: Optional[str] = None) -> str: return ( request.headers.get("X-Correlation-Id") or request.headers.get("X-Request-Id") or fallback_field or str(uuid.uuid4()) ) def _err(http_status: int, code: str, message: str, request_id: Optional[str] = None): detail = {"code": code, "message": message} if request_id: detail["request_id"] = request_id raise HTTPException(status_code=http_status, detail=detail) # ==================== 共享：payload 校验 ==================== ALLOWED_PROVIDERS = {"newapi", "litellm"} ALLOWED_RISK_LEVELS = {"low", "medium", "high"} ALLOWED_RESOURCE_TYPES_DEPLOYMENT = { "git", "sk", "project_doc", "cloud_account", "cloud_resource", "model_gateway_token", # P5 新增（按 §3a） } DEPLOYMENT_NON_TERMINAL = {"accepted", "pending", "running", "stopping", "processing"} DEPLOYMENT_TERMINAL = {"stopped", "completed", "failed", "cancelled"} def _validate_orchestration_plan(op: Dict[str, Any], request_id: str) -> None: """完整校验 orchestration_plan 结构，按契约 §2.3 + §8。""" if not isinstance(op, dict): _err(400, "POLICY_REJECTED", "orchestration_plan 必须是 object", request_id) required_fields = [ "intent_id", "template_hint", "objective", "risk_level", "budget", "metadata", "agents", ] for f in required_fields: if f not in op or op[f] in (None, "", [], {}): _err(400, "POLICY_REJECTED", f"orchestration_plan.{f} 必填", request_id) if op["risk_level"] not in ALLOWED_RISK_LEVELS: _err(400, "POLICY_REJECTED", f"risk_level 必须是 {sorted(ALLOWED_RISK_LEVELS)} 之一", request_id) bud = op.get("budget") or {} for f in ("max_tokens", "max_cost_usd", "max_duration_sec"): if f not in bud: _err(400, "POLICY_REJECTED", f"budget.{f} 必填", request_id) metadata = op.get("metadata") or {} if not metadata.get("correlation_id"): _err(400, "POLICY_REJECTED", "metadata.correlation_id 必填", request_id) # billing_context.provider 必须是 newapi 或 litellm bc = op.get("billing_context") or {} provider = bc.get("provider") if provider is not None and provider not in ALLOWED_PROVIDERS: _err(400, "POLICY_REJECTED", f"billing_context.provider 必须是 {sorted(ALLOWED_PROVIDERS)} 之一，收到 '{provider}'", request_id) # agents[] 至少 1 个 agents = op.get("agents") or [] if not isinstance(agents, list) or len(agents) == 0: _err(400, "POLICY_REJECTED", "orchestration_plan.agents 至少 1 项", request_id) # 校验每个 agent for i, agent in enumerate(agents): if not isinstance(agent, dict): _err(400, "POLICY_REJECTED", f"agents[{i}] 必须是 object", request_id) if not agent.get("role_template"): _err(400, "POLICY_REJECTED", f"agents[{i}].role_template 必填", request_id) if not agent.get("goal"): _err(400, "POLICY_REJECTED", f"agents[{i}].goal 必填", request_id) # default_model_id 若设置必须 ∈ allowed_model_ids constraints = op.get("constraints") or {} allowed = constraints.get("allowed_model_ids") or [] dmi = agent.get("default_model_id") if dmi and allowed and dmi not in allowed: _err(403, "MODEL_NOT_ALLOWED", f"agents[{i}].default_model_id='{dmi}' 不在 allowed_model_ids 内", request_id) # resource_grants[] 校验 grants = agent.get("resource_grants") or [] for j, g in enumerate(grants): if not isinstance(g, dict): _err(422, "RESOURCE_GRANT_INVALID", f"agents[{i}].resource_grants[{j}] 必须是 object", request_id) for f in ("grant_id", "resource_id", "resource_type", "user_id", "binding_scope", "target_role", "target_agent_ref", "permission_scope", "status"): if f not in g or g[f] in (None, ""): _err(422, "RESOURCE_GRANT_INVALID", f"agents[{i}].resource_grants[{j}].{f} 必填", request_id) if g["resource_type"] not in ALLOWED_RESOURCE_TYPES_DEPLOYMENT: _err(422, "RESOURCE_GRANT_INVALID", f"resource_grants[{j}].resource_type 不合法: {g['resource_type']}", request_id) # 凭据型必填 secret_ref if g["resource_type"] != "project_doc": if not g.get("secret_ref"): _err(422, "RESOURCE_GRANT_SECRET_REF_REQUIRED", f"agents[{i}].resource_grants[{j}].secret_ref 必填（{g['resource_type']}）", request_id) # role 一致 if g.get("target_role") and g["target_role"] != agent["role_template"]: _err(422, "RESOURCE_GRANT_INVALID", f"resource_grants[{j}].target_role 必须等于 agents[{i}].role_template", request_id) # high risk 必须有 approval_id if op["risk_level"] == "high": has_approval = False for g in grants: if (g.get("constraints") or {}).get("approval_id"): has_approval = True break if (g.get("audit") or {}).get("approval_id"): has_approval = True break if not has_approval: _err(403, "POLICY_REJECTED", "risk_level=high 必须在 resource_grants 的 constraints 或 audit 中携带 approval_id", request_id) # 敏感字段递归扫描 — **仅** scan 契约 §8.3 列出的字段：metadata / constraints / audit # 不能扫 budget（含 max_tokens）/ billing_context（含 newapi_token_or_group_quota_ref）/ # agent_runtime / orchestration_plan 顶层（避免误杀合法字段名） if isinstance(op.get("metadata"), dict): reject_sensitive_keys(op["metadata"], "orchestration_plan.metadata.") for i, agent in enumerate(op.get("agents", [])): for j, g in enumerate(agent.get("resource_grants") or []): base = f"orchestration_plan.agents[{i}].resource_grants[{j}]" for sub in ("metadata", "constraints", "audit"): v = g.get(sub) if isinstance(v, dict): reject_sensitive_keys(v, f"{base}.{sub}.") # ==================== 1. POST /deployments ==================== @router.post("/deployments", response_model=SuccessResponse) async def create_deployment( payload: Dict[str, Any], request: Request, principal: dict = Depends(require_auth), ): request_id = _correlation_id(request) idempotency_key = request.headers.get("Idempotency-Key") # 幂等：同 key 命中直接返回缓存结果 if idempotency_key: async with _store.lock: cached = _store.idempotency_cache.get(idempotency_key) if cached: return SuccessResponse(data=cached) op = payload.get("orchestration_plan") if not op: _err(400, "POLICY_REJECTED", "请求体缺少 orchestration_plan", request_id) _validate_orchestration_plan(op, request_id) # 创建 deployment deployment_id = _new_id("dep") now = _now_iso() user_id = (op.get("user_context") or {}).get("user_id") or \ request.headers.get("X-User-Id") binding_scope = (op.get("user_context") or {}).get("channel_id") or \ request.headers.get("X-Binding-Scope") or "default" correlation_id_field = (op.get("metadata") or {}).get("correlation_id", request_id) instances = [] for agent in op.get("agents", []): instances.append({ "instance_id": _new_id("agi"), "role": agent["role_template"], "phase": "pending", }) deployment = { "deployment_id": deployment_id, "status": "accepted", "phase": "pending", "agent_instances": instances, "user_id": user_id, "binding_scope": binding_scope, "correlation_id": correlation_id_field, "intent_id": op.get("intent_id"), "risk_level": op.get("risk_level"), "budget": op.get("budget"), "billing_context": op.get("billing_context"), "agent_runtime": op.get("agent_runtime"), "resource_grants_summary": [ { "grant_id": g.get("grant_id"), "resource_type": g.get("resource_type"), "binding_scope": g.get("binding_scope"), "target_role": g.get("target_role"), "permission_scope": g.get("permission_scope"), "status": g.get("status"), } for agent in op.get("agents", []) for g in (agent.get("resource_grants") or []) ], "budget_consumed": {"tokens_used": 0, "cost_usd": 0.0, "duration_sec": 0}, "last_error": None, "created_at": now, "updated_at": now, } # seed events events = [{ "event_id": _new_id("evt"), "event": "deployment.accepted", "schema_version": 1, "user_id": user_id, "channel_id": binding_scope, "binding_scope": binding_scope, "deployment_id": deployment_id, "correlation_id": correlation_id_field, "occurred_at": now, }] for ins in instances: events.append({ "event_id": _new_id("evt"), "event": "instance.phase_changed", "schema_version": 1, "user_id": user_id, "channel_id": binding_scope, "binding_scope": binding_scope, "deployment_id": deployment_id, "instance_id": ins["instance_id"], "phase": "pending", "correlation_id": correlation_id_field, "occurred_at": now, }) # seed logs（脱敏占位） logs = [{ "log_id": _new_id("log"), "deployment_id": deployment_id, "agent_instance_id": instances[0]["instance_id"] if instances else None, "stream": "system", "level": "info", "message": "[stub] deployment accepted, awaiting K8s bring-up", "redacted": True, "occurred_at": now, }] # audit audit_entry = { "audit_id": _new_id("aud"), "actor": "manager", "action": "deployment.accepted", "resource": deployment_id, "user_id": user_id, "channel_id": binding_scope, "binding_scope": binding_scope, "request_id": request_id, "correlation_id": correlation_id_field, "result": "ok", "occurred_at": now, } async with _store.lock: _store.deployments[deployment_id] = deployment _store.events[deployment_id] = events _store.logs[deployment_id] = logs _store.sk_snapshots[deployment_id] = [] _store.audit_logs.append(audit_entry) response_data = { "deployment_id": deployment_id, "status": "accepted", "agent_instances": instances, } if idempotency_key: _store.idempotency_cache[idempotency_key] = response_data return SuccessResponse(data=response_data) # ==================== 2-4. 部署列表 / 详情 / 停止 ==================== @router.get("/deployments", response_model=SuccessResponse) async def list_deployments( request: Request, principal: dict = Depends(require_auth), user_id: Optional[str] = Query(None), binding_scope: Optional[str] = Query(None), status_filter: Optional[str] = Query(None, alias="status"), limit: int = Query(50, ge=1, le=500), cursor: Optional[str] = Query(None), ): async with _store.lock: items = [] for d in _store.deployments.values(): if user_id and d.get("user_id") != user_id: continue if binding_scope and d.get("binding_scope") != binding_scope: continue if status_filter and d.get("status") != status_filter: continue items.append({ "deployment_id": d["deployment_id"], "status": d["status"], "phase": d["phase"], "user_id": d.get("user_id"), "binding_scope": d.get("binding_scope"), "created_at": d["created_at"], "updated_at": d["updated_at"], }) items.sort(key=lambda x: x["created_at"], reverse=True) items = items[:limit] return SuccessResponse(data={"items": items, "total": len(items)}) @router.get("/deployments/{deployment_id}", response_model=SuccessResponse) async def get_deployment( deployment_id: str, request: Request, principal: dict = Depends(require_auth), ): async with _store.lock: d = _store.deployments.get(deployment_id) if d is None: _err(404, "NOT_FOUND", f"部署 {deployment_id} 不存在", _correlation_id(request)) return SuccessResponse(data=d) @router.post("/deployments/{deployment_id}/stop", response_model=SuccessResponse) async def stop_deployment( deployment_id: str, request: Request, principal: dict = Depends(require_auth), payload: Optional[Dict[str, Any]] = None, ): request_id = _correlation_id(request) async with _store.lock: d = _store.deployments.get(deployment_id) if d is None: _err(404, "NOT_FOUND", f"部署 {deployment_id} 不存在", request_id) # 幂等：已 stopped 重复 stop 仍返 200 if d["status"] == "stopped": return SuccessResponse(data={ "deployment_id": deployment_id, "status": "stopped", }) # 终态（completed 等）拒绝 if d["status"] in DEPLOYMENT_TERMINAL and d["status"] != "stopped": _err(409, "DEPLOYMENT_CONFLICT", f"部署已进入终态 {d['status']}，不能停止", request_id) d["status"] = "stopped" d["phase"] = "stopped" d["updated_at"] = _now_iso() for ins in d.get("agent_instances", []): ins["phase"] = "stopped" # event _store.events[deployment_id].append({ "event_id": _new_id("evt"), "event": "deployment.stopped", "schema_version": 1, "user_id": d.get("user_id"), "channel_id": d.get("binding_scope"), "binding_scope": d.get("binding_scope"), "deployment_id": deployment_id, "correlation_id": d.get("correlation_id"), "occurred_at": d["updated_at"], }) # audit _store.audit_logs.append({ "audit_id": _new_id("aud"), "actor": "manager", "action": "deployment.stop", "resource": deployment_id, "user_id": d.get("user_id"), "binding_scope": d.get("binding_scope"), "request_id": request_id, "correlation_id": d.get("correlation_id"), "result": "ok", "occurred_at": d["updated_at"], }) return SuccessResponse(data={ "deployment_id": deployment_id, "status": "stopped", }) # ==================== 5-6. 日志 + SSE ==================== @router.get("/deployments/{deployment_id}/logs", response_model=SuccessResponse) async def list_logs( deployment_id: str, request: Request, principal: dict = Depends(require_auth), agent_instance_id: Optional[str] = Query(None), stream: Optional[str] = Query(None), since: Optional[str] = Query(None), limit: int = Query(200, ge=1, le=1000), cursor: Optional[str] = Query(None), ): async with _store.lock: if deployment_id not in _store.deployments: _err(404, "NOT_FOUND", f"部署 {deployment_id} 不存在", _correlation_id(request)) logs = list(_store.logs.get(deployment_id, [])) # 过滤 if agent_instance_id: logs = [l for l in logs if l.get("agent_instance_id") == agent_instance_id] if stream: logs = [l for l in logs if l.get("stream") == stream] if since: logs = [l for l in logs if (l.get("occurred_at") or "") >= since] return SuccessResponse(data={ "items": logs[:limit], "next_cursor": None, "total": len(logs), }) @router.get("/deployments/{deployment_id}/logs/stream") async def stream_logs( deployment_id: str, request: Request, principal: dict = Depends(require_auth), agent_instance_id: Optional[str] = Query(None), ): async with _store.lock: if deployment_id not in _store.deployments: _err(404, "NOT_FOUND", f"部署 {deployment_id} 不存在", _correlation_id(request)) async def gen(): # 发送 2 条 mock log + 1 个 heartbeat + done for i in range(2): line = { "log_id": _new_id("log"), "deployment_id": deployment_id, "level": "info", "message": f"[stub-stream] mock log line {i+1}", "occurred_at": _now_iso(), } yield f"event: log\ndata: {json.dumps(line)}\n\n" await asyncio.sleep(0.2) yield f"event: heartbeat\ndata: {{}}\n\n" await asyncio.sleep(0.2) yield f"event: done\ndata: {{}}\n\n" return StreamingResponse(gen(), media_type="text/event-stream") # ==================== 7-8. 监控快照 + metrics ==================== @router.get("/projects/{binding_scope}/dashboard-snapshot", response_model=SuccessResponse) async def dashboard_snapshot( binding_scope: str, request: Request, principal: dict = Depends(require_auth), window: str = Query("1h"), ): async with _store.lock: deps = [d for d in _store.deployments.values() if d.get("binding_scope") == binding_scope] phase_dist = {"pending": 0, "running": 0, "stopped": 0, "failed": 0} for d in deps: ph = d.get("phase", "pending") if ph not in phase_dist: phase_dist[ph] = 0 phase_dist[ph] += 1 return SuccessResponse(data={ "project_id": binding_scope, "binding_scope": binding_scope, "active_instances": sum(1 for d in deps if d.get("status") in DEPLOYMENT_NON_TERMINAL), "phase_distribution": phase_dist, "failure_rate_1h": 0.0, "avg_task_duration": 0.0, "budget": {"tokens_used": 0, "cost_usd": 0.0, "duration_sec": 0}, "resource_usage": { "cpu_millicores": 0, "memory_mb": 0, "network_rx_bytes": 0, "network_tx_bytes": 0, }, "updated_at": _now_iso(), }) @router.get("/deployments/{deployment_id}/metrics", response_model=SuccessResponse) async def deployment_metrics( deployment_id: str, request: Request, principal: dict = Depends(require_auth), window: str = Query("15m"), step: str = Query("60s"), ): async with _store.lock: if deployment_id not in _store.deployments: _err(404, "NOT_FOUND", f"部署 {deployment_id} 不存在", _correlation_id(request)) now = _now_iso() series = [ {"metric": "tokens_used", "unit": "count", "points": [[now, 0]]}, {"metric": "cost_usd", "unit": "usd", "points": [[now, 0.0]]}, {"metric": "duration_sec", "unit": "count", "points": [[now, 0]]}, {"metric": "cpu_millicores", "unit": "millicore", "points": [[now, 0]]}, {"metric": "memory_mb", "unit": "mb", "points": [[now, 0]]}, {"metric": "restart_count", "unit": "count", "points": [[now, 0]]}, {"metric": "tool_call_count", "unit": "count", "points": [[now, 0]]}, {"metric": "error_count", "unit": "count", "points": [[now, 0]]}, {"metric": "queue_latency_ms", "unit": "ms", "points": [[now, 0]]}, ] return SuccessResponse(data={ "deployment_id": deployment_id, "window": window, "step": step, "series": series, }) # ==================== 9-10. 事件 + 审计 ==================== @router.get("/deployments/{deployment_id}/events", response_model=SuccessResponse) async def list_events( deployment_id: str, request: Request, principal: dict = Depends(require_auth), since: Optional[str] = Query(None), limit: int = Query(200, ge=1, le=1000), cursor: Optional[str] = Query(None), ): async with _store.lock: if deployment_id not in _store.deployments: _err(404, "NOT_FOUND", f"部署 {deployment_id} 不存在", _correlation_id(request)) events = list(_store.events.get(deployment_id, [])) if since: events = [e for e in events if (e.get("occurred_at") or "") >= since] return SuccessResponse(data={ "items": events[:limit], "next_cursor": None, "total": len(events), }) @router.get("/audit-logs", response_model=SuccessResponse) async def list_audit_logs( request: Request, principal: dict = Depends(require_auth), user_id: Optional[str] = Query(None), binding_scope: Optional[str] = Query(None), actor: Optional[str] = Query(None), action: Optional[str] = Query(None), since: Optional[str] = Query(None), limit: int = Query(200, ge=1, le=1000), cursor: Optional[str] = Query(None), ): async with _store.lock: items = list(_store.audit_logs) if user_id: items = [a for a in items if a.get("user_id") == user_id] if binding_scope: items = [a for a in items if a.get("binding_scope") == binding_scope] if actor: items = [a for a in items if a.get("actor") == actor] if action: items = [a for a in items if a.get("action") == action] if since: items = [a for a in items if (a.get("occurred_at") or "") >= since] items.sort(key=lambda a: a.get("occurred_at", ""), reverse=True) return SuccessResponse(data={ "items": items[:limit], "next_cursor": None, "total": len(items), }) # ==================== 11-12. SK 快照 ==================== @router.post("/sk-snapshots/resolve", response_model=SuccessResponse) async def resolve_sk_snapshot( payload: Dict[str, Any], request: Request, principal: dict = Depends(require_auth), ): request_id = _correlation_id(request) deployment_id = payload.get("deployment_id") if not deployment_id: _err(400, "POLICY_REJECTED", "deployment_id 必填", request_id) async with _store.lock: d = _store.deployments.get(deployment_id) if d is None: _err(404, "NOT_FOUND", f"部署 {deployment_id} 不存在", request_id) snap = { "snapshot_id": _new_id("sks"), "deployment_id": deployment_id, "user_id": d.get("user_id"), "binding_scope": d.get("binding_scope"), "source_type": "git", "source_ref": "main:skills/heicode/**@stub-checksum", "artifact_ref": f"artifact://stub/{deployment_id}/sks", "checksum": "sha256:stub-redacted", "status": "ready", "resolved_at": _now_iso(), } _store.sk_snapshots[deployment_id].append(snap) # event _store.events[deployment_id].append({ "event_id": _new_id("evt"), "event": "sk_snapshot_refreshed", "schema_version": 1, "user_id": d.get("user_id"), "binding_scope": d.get("binding_scope"), "deployment_id": deployment_id, "snapshot_id": snap["snapshot_id"], "occurred_at": snap["resolved_at"], }) return SuccessResponse(data={ "deployment_id": deployment_id, "items": [snap], "total": 1, }) @router.get("/deployments/{deployment_id}/sk-snapshots", response_model=SuccessResponse) async def list_sk_snapshots( deployment_id: str, request: Request, principal: dict = Depends(require_auth), user_id: Optional[str] = Query(None), binding_scope: Optional[str] = Query(None), source_type: Optional[str] = Query(None), limit: int = Query(100, ge=1, le=500), cursor: Optional[str] = Query(None), ): async with _store.lock: if deployment_id not in _store.deployments: _err(404, "NOT_FOUND", f"部署 {deployment_id} 不存在", _correlation_id(request)) items = list(_store.sk_snapshots.get(deployment_id, [])) if source_type: items = [s for s in items if s.get("source_type") == source_type] return SuccessResponse(data={ "items": items[:limit], "next_cursor": None, "total": len(items), })