This commit is contained in:
xuhd committed 2026-05-19 16:05:11 +08:00
commit 64492bec43
46 files changed
+3298 -313

No files matched your search

@@ -23,6 +23,7 @@ from app.gateway.csrf_middleware import CSRFMiddleware
from app.gateway.deps import langgraph_runtime
from app.gateway.routers import (
ai_writing,
admin_users,
agents,
artifacts,
assistants_compat,
@@ -42,6 +43,7 @@ from app.gateway.routers import (
system_settings,
tags,
thread_runs,
tool_metrics,
thread_shares,
threads,
uploads,
@@ -256,7 +258,7 @@ async def _run_db_migrations() -> None:
logger.info("Persistence backend=memory — skipping Alembic migrations")
return
db_url = engine.url.render_as_string(hide_password=False).replace("%", "%%")
db_url = engine.url.render_as_string(hide_password=False).replace("%", "%%")
migrations_dir = str(Path(_persistence_pkg.__file__).parent / "migrations")
def _run_sync() -> None:
@@ -689,6 +691,12 @@ This gateway provides custom endpoints for models, MCP configuration, skills, an
# Admin LLM metrics audit + export
app.include_router(llm_metrics.router)
# Admin window into other users' threads / messages / memory
app.include_router(admin_users.router)
# Admin tool / skill call metrics audit + export
app.include_router(tool_metrics.router)
# Channels API is mounted at /api/channels
app.include_router(channels.router)
@@ -97,6 +97,10 @@ async def langgraph_runtime(app: FastAPI) -> AsyncGenerator[None, None]:
app.state.llm_metrics_store = make_llm_metrics_store(sf)
from deerflow.persistence.tool_metrics import make_tool_metrics_store
app.state.tool_metrics_store = make_tool_metrics_store(sf)
from deerflow.persistence.agents import make_agent_store
app.state.agent_store = make_agent_store(sf)
@@ -202,6 +206,11 @@ def get_llm_metrics_store(request: Request):
return getattr(request.app.state, "llm_metrics_store", None)
def get_tool_metrics_store(request: Request):
"""Return the tool-call metrics store, or None when not configured."""
return getattr(request.app.state, "tool_metrics_store", None)
def get_agent_store(request: Request) -> AgentStore:
"""Return the custom-agent store."""
val = getattr(request.app.state, "agent_store", None)
@@ -0,0 +1,162 @@
"""Admin-only window into another user's activity.
Lets an administrator inspect any user's conversation history (threads + the
Q&A messages inside them) and their accumulated memory (global + per-agent
buckets). All endpoints require ``system_role == "admin"``; they are strictly
read-only.
The underlying stores normally auto-scope every query to the *calling* user
via a contextvar. These endpoints pass an explicit ``user_id`` so the admin
reads the *target* user's data instead — which is exactly what those store
methods' ``user_id`` parameter is designed for.
"""
from __future__ import annotations
import logging
from fastapi import APIRouter, HTTPException, Query, Request
from pydantic import BaseModel, Field
from app.gateway.deps import (
get_checkpointer,
get_current_user_from_request,
get_thread_store,
)
from deerflow.agents.memory.updater import get_memory_data
from deerflow.config.agents_config import AGENT_NAME_PATTERN
from deerflow.config.paths import get_paths
from deerflow.runtime import serialize_channel_values
logger = logging.getLogger(__name__)
router = APIRouter(prefix="/api/admin/users", tags=["admin-users"])
async def _require_admin(request: Request) -> None:
"""Reject non-admin callers. In no-auth mode there is no user → allow."""
try:
user = await get_current_user_from_request(request)
except HTTPException:
raise
if user is None:
return
if getattr(user, "system_role", None) != "admin":
raise HTTPException(status_code=403, detail="Admin only")
# ── Threads ────────────────────────────────────────────────────────────────
class AdminThreadItem(BaseModel):
thread_id: str
display_name: str = ""
status: str = "idle"
created_at: str = ""
updated_at: str = ""
@router.get("/{user_id}/threads", response_model=list[AdminThreadItem])
async def list_user_threads(
user_id: str,
request: Request,
limit: int = Query(default=100, ge=1, le=500),
offset: int = Query(default=0, ge=0),
) -> list[AdminThreadItem]:
"""List one user's conversation threads, newest first."""
await _require_admin(request)
repo = get_thread_store(request)
rows = await repo.search(limit=limit, offset=offset, user_id=user_id)
return [
AdminThreadItem(
thread_id=r["thread_id"],
display_name=r.get("display_name") or "",
status=r.get("status", "idle"),
created_at=str(r.get("created_at") or ""),
updated_at=str(r.get("updated_at") or ""),
)
for r in rows
]
@router.get("/{user_id}/threads/{thread_id}/messages", response_model=list[dict])
async def list_user_thread_messages(
user_id: str,
thread_id: str,
request: Request,
limit: int = Query(default=400, ge=1, le=1000),
) -> list[dict]:
"""Return the conversation messages of one of the user's threads.
Read straight from the LangGraph checkpoint — the same source the chat UI
renders — rather than the optional ``run_events`` audit log, which may be
unconfigured (``run_events.backend=memory``) or empty for older threads.
"""
await _require_admin(request)
repo = get_thread_store(request)
# ``user_id=None`` bypasses the owner filter so the admin can fetch any row;
# we then assert the thread really belongs to the target user.
thread = await repo.get(thread_id, user_id=None)
if thread is None:
raise HTTPException(status_code=404, detail="Thread not found")
owner = thread.get("user_id")
if owner is not None and owner != user_id:
raise HTTPException(status_code=404, detail="Thread does not belong to this user")
checkpointer = get_checkpointer(request)
config = {"configurable": {"thread_id": thread_id, "checkpoint_ns": ""}}
try:
checkpoint_tuple = await checkpointer.aget_tuple(config)
except Exception as exc: # noqa: BLE001 - surface a clean error
logger.error("Failed to read checkpoint for thread %s: %s", thread_id, exc, exc_info=True)
raise HTTPException(status_code=500, detail="Failed to read thread state") from exc
if checkpoint_tuple is None:
return []
checkpoint = getattr(checkpoint_tuple, "checkpoint", {}) or {}
channel_values = checkpoint.get("channel_values", {}) if isinstance(checkpoint, dict) else {}
values = serialize_channel_values(channel_values)
messages = values.get("messages", [])
if not isinstance(messages, list):
return []
# Keep the most recent ``limit`` messages — long threads stay bounded.
return messages[-limit:]
# ── Memory ─────────────────────────────────────────────────────────────────
class AdminMemoryBucket(BaseModel):
name: str = Field(..., description="Bucket name: 'global' or a custom-agent name")
data: dict = Field(default_factory=dict, description="Raw memory data for the bucket")
class AdminMemoryResponse(BaseModel):
user_id: str
buckets: list[AdminMemoryBucket] = Field(default_factory=list)
@router.get("/{user_id}/memory", response_model=AdminMemoryResponse)
async def get_user_memory(user_id: str, request: Request) -> AdminMemoryResponse:
"""Return every memory bucket (global + per-agent) for one user."""
await _require_admin(request)
buckets: list[AdminMemoryBucket] = [
AdminMemoryBucket(name="global", data=get_memory_data(None, user_id=user_id))
]
agents_root = get_paths().user_dir(user_id) / "agents"
if agents_root.is_dir():
for entry in sorted(agents_root.iterdir(), key=lambda p: p.name.lower()):
if not entry.is_dir() or not (entry / "memory.json").exists():
continue
if not AGENT_NAME_PATTERN.match(entry.name):
continue
try:
data = get_memory_data(entry.name, user_id=user_id)
except Exception:
logger.warning("Failed to read memory bucket %s for user", entry.name)
continue
buckets.append(AdminMemoryBucket(name=entry.name, data=data))
return AdminMemoryResponse(user_id=user_id, buckets=buckets)
@@ -244,7 +244,7 @@ async def _get_editable_or_raise(
async def list_agents(
request: Request,
search: str | None = Query(default=None, description="Case-insensitive fuzzy match on agent name"),
tag_id: str | None = Query(default=None, description="Keep only agents carrying this tag"),
tag_ids: list[str] | None = Query(default=None, description="Keep agents carrying any of these tags (OR)"),
) -> AgentsListResponse:
_require_agents_api_enabled()
@@ -262,8 +262,9 @@ async def list_agents(
if search:
needle = search.strip().lower()
responses = [r for r in responses if needle in r.name.lower()]
if tag_id:
responses = [r for r in responses if any(t.get("id") == tag_id for t in r.tags)]
if tag_ids:
wanted = set(tag_ids)
responses = [r for r in responses if any(t.get("id") in wanted for t in r.tags)]
return AgentsListResponse(agents=responses)
except HTTPException:
raise
@@ -197,7 +197,7 @@ async def get_scheduler_thread(request: Request) -> dict:
async def list_scheduled_tasks(
request: Request,
search: str | None = Query(default=None, description="Case-insensitive fuzzy match on task name"),
tag_id: str | None = Query(default=None, description="Keep only tasks carrying this tag"),
tag_ids: list[str] | None = Query(default=None, description="Keep tasks carrying any of these tags (OR)"),
) -> list[dict]:
service = get_scheduled_task_service()
user_id = await _user_id(request)
@@ -211,8 +211,9 @@ async def list_scheduled_tasks(
if search:
needle = search.strip().lower()
tasks = [t for t in tasks if needle in str(t.get("name", "")).lower()]
if tag_id:
tasks = [t for t in tasks if any(tg.get("id") == tag_id for tg in t.get("tags", []))]
if tag_ids:
wanted = set(tag_ids)
tasks = [t for t in tasks if any(tg.get("id") in wanted for tg in t.get("tags", []))]
return tasks
@@ -236,7 +236,7 @@ async def _attach_and_filter_tags(
tag_store: TagStore,
responses: list[SkillResponse],
search: str | None,
tag_id: str | None,
tag_ids: list[str] | None,
) -> list[SkillResponse]:
"""Bulk-attach tags to skill responses, then apply name/tag filters."""
assignments = await tag_store.list_assignments("skill", [r.name for r in responses])
@@ -245,8 +245,9 @@ async def _attach_and_filter_tags(
if search:
needle = search.strip().lower()
responses = [r for r in responses if needle in r.name.lower()]
if tag_id:
responses = [r for r in responses if any(t.get("id") == tag_id for t in r.tags)]
if tag_ids:
wanted = set(tag_ids)
responses = [r for r in responses if any(t.get("id") in wanted for t in r.tags)]
return responses
@@ -262,7 +263,7 @@ async def list_skills(
skill_store: SkillStore = Depends(get_skill_store),
tag_store: TagStore = Depends(get_tag_store),
search: str | None = Query(default=None, description="Case-insensitive fuzzy match on skill name"),
tag_id: str | None = Query(default=None, description="Keep only skills carrying this tag"),
tag_ids: list[str] | None = Query(default=None, description="Keep skills carrying any of these tags (OR)"),
) -> SkillsListResponse:
try:
user_id = _current_user_id(request)
@@ -281,7 +282,7 @@ async def list_skills(
if record is None:
continue
responses.append(_skill_to_response(skill, record))
responses = await _attach_and_filter_tags(tag_store, responses, search, tag_id)
responses = await _attach_and_filter_tags(tag_store, responses, search, tag_ids)
return SkillsListResponse(skills=responses)
except Exception as e:
logger.error(f"Failed to load skills: {e}", exc_info=True)
@@ -294,20 +294,38 @@ async def get_public_share_snapshot(
)
# Content types that can execute scripts in the app origin — always served as
# a download attachment so a shared file can never run as a top-level document.
_PUBLIC_SHARE_ACTIVE_TYPES = {"text/html", "application/xhtml+xml", "image/svg+xml"}
def _public_share_disposition(mime_type: str) -> str:
"""Pick a Content-Disposition for a public-share file.
Active content (HTML/XHTML/SVG) is forced to ``attachment`` so it cannot
execute as a top-level document; everything else (images, Markdown, text,
PDF, …) is served ``inline`` so viewers can open it directly.
"""
return "attachment" if mime_type in _PUBLIC_SHARE_ACTIVE_TYPES else "inline"
@public_router.get(
"/{share_code}/files/{path:path}",
summary="Public image attachment from a view-shared conversation",
summary="Public file attachment from a view-shared conversation",
)
async def get_public_share_file(
share_code: str,
path: str,
share_store: ThreadShareStore = Depends(get_thread_share_store),
) -> FileResponse:
"""Serve an image referenced by a view-shared conversation.
"""Serve a file referenced by a view-shared conversation.
Restricted to images only — the public share page renders inline images,
but the endpoint must not become a way to read arbitrary thread files.
Non-image paths return 404 just like a missing file.
A ``view`` share is a public read-only page, so the files its conversation
references (images, Markdown, text, PDF, …) must be openable. Path
resolution is confined to the owner's thread directory, so this cannot read
arbitrary files. Active content (HTML/XHTML/SVG) is forced to download so it
can never execute as a top-level document in the app origin; everything
else is served inline.
"""
share = await share_store.get(share_code)
if share is None or share.get("revoked") or share.get("mode") != "view":
@@ -324,17 +342,10 @@ async def get_public_share_file(
if not actual_path.exists() or not actual_path.is_file():
raise HTTPException(status_code=404, detail="File not found")
mime_type, _ = mimetypes.guess_type(actual_path.name)
if not mime_type or not mime_type.startswith("image/"):
# Only images are public; everything else is treated as not found.
raise HTTPException(status_code=404, detail="File not found")
# SVG can carry scripts — serve it as a download so it can never execute
# as a top-level document in the app origin. Raster images render inline.
is_svg = mime_type == "image/svg+xml"
mime_type = mimetypes.guess_type(actual_path.name)[0] or "application/octet-stream"
return FileResponse(
actual_path,
media_type=mime_type,
content_disposition_type="attachment" if is_svg else "inline",
content_disposition_type=_public_share_disposition(mime_type),
headers={"Cache-Control": "public, max-age=300"},
)
@@ -0,0 +1,380 @@
"""Admin-only tool / skill call metrics: list + Excel export.
Companion to ``llm_metrics`` — where that audits every LLM provider call, this
audits every *tool* call (built-in tools, skills, MCP tools, subagent calls),
including the failures: retrieval errors, blocked/rate-limited IPs, timeouts,
auth problems. Failures are bucketed into a coarse ``error_category`` so an
admin can scan for systemic issues.
"""
from __future__ import annotations
import logging
from datetime import datetime
from io import BytesIO
from typing import Any
from urllib.parse import quote
from fastapi import APIRouter, HTTPException, Query, Request
from fastapi.responses import StreamingResponse
from pydantic import BaseModel, Field
from app.gateway.deps import get_local_provider, get_optional_user_from_request, get_tool_metrics_store
from deerflow.persistence.tool_metrics.base import ToolMetricsQuery, ToolMetricsStore
logger = logging.getLogger(__name__)
router = APIRouter(prefix="/api/admin/tool-metrics", tags=["tool-metrics"])
_VALID_CATEGORIES = (
"rate_limited",
"ip_blocked",
"auth_error",
"timeout",
"network_error",
"not_found",
"empty_result",
"tool_error",
)
def _kind_is_skill(kind: str | None) -> bool:
"""``kind=skill`` keeps only rows that target a specific Agent Skill."""
return kind == "skill"
class ToolMetricResponse(BaseModel):
id: str
created_at: str | None = None
user_id: str | None = None
user_name: str | None = Field(
default=None,
description="Local part (before @) of the user's email, resolved from user_id",
)
thread_id: str | None = None
run_id: str | None = None
agent_name: str | None = None
tool_name: str | None = None
skill_name: str | None = Field(
default=None,
description="The Agent Skill this call targets (skill tools only)",
)
duration_ms: int = 0
status: str = "success"
error_category: str | None = None
error_message: str | None = None
class ToolMetricsListResponse(BaseModel):
items: list[ToolMetricResponse]
total: int = Field(..., description="Total rows matching the filter, ignoring pagination")
limit: int
offset: int
async def _require_admin(request: Request) -> None:
user = await get_optional_user_from_request(request)
if user is None:
return
if getattr(user, "system_role", None) != "admin":
raise HTTPException(status_code=403, detail="Tool metrics admin view is admin-only")
def _require_store(request: Request) -> ToolMetricsStore:
store = get_tool_metrics_store(request)
if store is None:
raise HTTPException(status_code=503, detail="Tool metrics store is not configured")
return store
def _parse_dt(value: str | None) -> datetime | None:
if not value:
return None
try:
return datetime.fromisoformat(value.replace("Z", "+00:00"))
except ValueError as exc:
raise HTTPException(status_code=422, detail=f"Invalid datetime: {value!r} ({exc})") from exc
def _email_local_part(email: str | None) -> str | None:
if not email:
return None
at = email.find("@")
return email[:at] if at > 0 else email
async def _resolve_user_name_to_id(name: str | None) -> str | None:
if not name:
return None
try:
provider = get_local_provider()
user = await provider.find_user_by_email_local_part(name)
except Exception:
return None
return str(user.id) if user is not None else None
async def _attach_usernames(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
"""Resolve each row's ``user_id`` UUID to a friendly ``user_name``."""
if not rows:
return rows
user_ids = {row["user_id"] for row in rows if isinstance(row, dict) and row.get("user_id")}
if not user_ids:
return rows
try:
provider = get_local_provider()
except Exception:
provider = None
email_by_id: dict[str, str] = {}
if provider is not None:
for uid in user_ids:
try:
user = await provider.get_user(uid)
except Exception:
user = None
if user is not None and user.email:
email_by_id[uid] = user.email
for row in rows:
if isinstance(row, dict) and row.get("user_id"):
email = email_by_id.get(row["user_id"])
row["user_name"] = _email_local_part(email) or row["user_id"]
return rows
def _build_query(
*,
user_id: str | None,
tool_name: str | None,
skill_only: bool = False,
skill_name: str | None = None,
status: str | None,
error_category: str | None,
since: str | None,
until: str | None,
limit: int,
offset: int,
) -> ToolMetricsQuery:
return ToolMetricsQuery(
user_id=user_id or None,
tool_name=tool_name or None,
skill_only=skill_only,
skill_name=skill_name or None,
status=status or None,
error_category=error_category or None,
since=_parse_dt(since),
until=_parse_dt(until),
limit=limit,
offset=offset,
)
@router.get("", response_model=ToolMetricsListResponse)
async def list_tool_metrics(
request: Request,
user_id: str | None = Query(default=None),
user_name: str | None = Query(default=None, description="Username (email local part) to filter by"),
tool_name: str | None = Query(default=None),
kind: str | None = Query(default=None, description="Coarse call kind: 'skill' keeps only Agent-Skill invocations"),
skill_name: str | None = Query(default=None, description="Filter to one specific Agent Skill by name"),
status: str | None = Query(default=None, pattern="^(success|error)$"),
error_category: str | None = Query(default=None, description="Coarse failure bucket"),
since: str | None = Query(default=None, description="ISO 8601 datetime, inclusive lower bound"),
until: str | None = Query(default=None, description="ISO 8601 datetime, inclusive upper bound"),
limit: int = Query(default=50, ge=1, le=500),
offset: int = Query(default=0, ge=0),
) -> ToolMetricsListResponse:
await _require_admin(request)
store = _require_store(request)
if error_category and error_category not in _VALID_CATEGORIES:
raise HTTPException(status_code=422, detail=f"Unknown error_category: {error_category!r}")
if not user_id and user_name:
resolved = await _resolve_user_name_to_id(user_name)
if resolved is None:
return ToolMetricsListResponse(items=[], total=0, limit=limit, offset=offset)
user_id = resolved
query = _build_query(
user_id=user_id,
tool_name=tool_name,
skill_only=_kind_is_skill(kind),
skill_name=skill_name,
status=status,
error_category=error_category,
since=since,
until=until,
limit=limit,
offset=offset,
)
rows = await store.list(query)
total = await store.count(query)
await _attach_usernames(rows)
return ToolMetricsListResponse(
items=[ToolMetricResponse(**row) for row in rows],
total=total,
limit=limit,
offset=offset,
)
class SkillStat(BaseModel):
skill_name: str
total: int
success: int
error: int
class ToolMetricsSummaryResponse(BaseModel):
total: int
error_total: int
by_category: dict[str, int] = Field(default_factory=dict)
by_skill: list[SkillStat] = Field(
default_factory=list,
description="Per-skill invocation counts — answers 'was skill X called, and did it succeed'",
)
@router.get("/summary", response_model=ToolMetricsSummaryResponse)
async def tool_metrics_summary(
request: Request,
user_id: str | None = Query(default=None),
user_name: str | None = Query(default=None),
tool_name: str | None = Query(default=None),
kind: str | None = Query(default=None),
skill_name: str | None = Query(default=None),
since: str | None = Query(default=None),
until: str | None = Query(default=None),
) -> ToolMetricsSummaryResponse:
"""Aggregate counts: total, errors, per-category breakdown, and per-skill stats."""
await _require_admin(request)
store = _require_store(request)
if not user_id and user_name:
resolved = await _resolve_user_name_to_id(user_name)
if resolved is None:
return ToolMetricsSummaryResponse(total=0, error_total=0, by_category={}, by_skill=[])
user_id = resolved
skill_only = _kind_is_skill(kind)
def _q(*, status: str | None = None, error_category: str | None = None) -> ToolMetricsQuery:
return _build_query(
user_id=user_id,
tool_name=tool_name,
skill_only=skill_only,
skill_name=skill_name,
status=status,
error_category=error_category,
since=since,
until=until,
limit=1,
offset=0,
)
total = await store.count(_q())
error_total = await store.count(_q(status="error"))
by_category: dict[str, int] = {}
for category in _VALID_CATEGORIES:
count = await store.count(_q(status="error", error_category=category))
if count:
by_category[category] = count
by_skill = [SkillStat(**row) for row in await store.skill_breakdown(_q())]
return ToolMetricsSummaryResponse(
total=total, error_total=error_total, by_category=by_category, by_skill=by_skill
)
def _format_cell(value: Any) -> Any:
if value is None:
return ""
if isinstance(value, datetime):
return value.replace(tzinfo=None) if value.tzinfo else value
return value
@router.get("/export")
async def export_tool_metrics(
request: Request,
user_id: str | None = Query(default=None),
user_name: str | None = Query(default=None),
tool_name: str | None = Query(default=None),
kind: str | None = Query(default=None),
skill_name: str | None = Query(default=None),
status: str | None = Query(default=None, pattern="^(success|error)$"),
error_category: str | None = Query(default=None),
since: str | None = Query(default=None),
until: str | None = Query(default=None),
):
"""Stream the full filtered metric set as an ``.xlsx`` file."""
await _require_admin(request)
store = _require_store(request)
if not user_id and user_name:
resolved = await _resolve_user_name_to_id(user_name)
user_id = resolved if resolved is not None else "__no_such_user__"
try:
from openpyxl import Workbook
except ImportError as exc:
raise HTTPException(status_code=500, detail=f"openpyxl is not installed: {exc}") from exc
query = _build_query(
user_id=user_id,
tool_name=tool_name,
skill_only=_kind_is_skill(kind),
skill_name=skill_name,
status=status,
error_category=error_category,
since=since,
until=until,
limit=1,
offset=0,
)
workbook = Workbook(write_only=True)
sheet = workbook.create_sheet("tool_call_metrics")
columns = [
"id",
"created_at",
"status",
"error_category",
"user_name",
"user_id",
"thread_id",
"run_id",
"agent_name",
"tool_name",
"skill_name",
"duration_ms",
"error_message",
]
sheet.append(columns)
buffered: list[dict[str, Any]] = []
FLUSH_AT = 200
async def flush() -> int:
if not buffered:
return 0
await _attach_usernames(buffered)
for row in buffered:
sheet.append([_format_cell(row.get(col)) for col in columns])
n = len(buffered)
buffered.clear()
return n
count = 0
async for row in store.iter_all(query):
buffered.append(row)
if len(buffered) >= FLUSH_AT:
count += await flush()
count += await flush()
buffer = BytesIO()
workbook.save(buffer)
buffer.seek(0)
logger.info("Exported %d tool_call_metrics rows", count)
timestamp = datetime.utcnow().strftime("%Y%m%d-%H%M%S")
filename = f"tool_call_metrics-{timestamp}.xlsx"
headers = {
"Content-Disposition": f"attachment; filename=\"{filename}\"; filename*=UTF-8''{quote(filename)}",
}
return StreamingResponse(
buffer,
media_type="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
headers=headers,
)