feat: 标签管理功能 + 问答前缀对用户隐藏

标签管理:
- 新增 tags/tag_assignments 持久化层、迁移、/api/tags 路由
- 标签分智能体/技能/定时任务三类, 仅同类型可互打, 仅 admin 可增删改与打标签
- 三类资源列表支持按名称模糊检索与按标签筛选(走后端查询参数)
- 前端新增标签管理页、TagPickerDialog(点击即时绑定)、彩色标签 chip

问答前缀:
- 前缀不再拼入消息 content, 改存 additional_kwargs 由 PromptPrefixMiddleware
  在调模型前临时注入, 用户界面看不到前缀但模型仍收到
- 修正 thread_existed 闸门导致首轮前缀被跳过的问题

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
吉鑫升andClaude Opus 4.7 committed 2026-05-15 16:19:08 +08:00
1 parent aeba15eb16
commit 646cb8caeb
47 files changed
+2180 -109

No files matched your search

@@ -38,6 +38,7 @@ from app.gateway.routers import (
skills,
suggestions,
system_settings,
tags,
thread_runs,
threads,
uploads,
@@ -595,6 +596,9 @@ This gateway provides custom endpoints for models, MCP configuration, skills, an
# Notifications API is mounted at /api/notifications
app.include_router(notifications.router)
# Tags API is mounted at /api/tags
app.include_router(tags.router)
# Thread Runs API (LangGraph Platform-compatible runs lifecycle)
app.include_router(thread_runs.router)
@@ -28,6 +28,7 @@ if TYPE_CHECKING:
from deerflow.persistence.notifications import NotificationStore
from deerflow.persistence.scheduled_tasks import ScheduledTaskStore
from deerflow.persistence.skills import SkillStore
from deerflow.persistence.tags import TagStore
from deerflow.persistence.thread_meta.base import ThreadMetaStore
@@ -117,6 +118,10 @@ async def langgraph_runtime(app: FastAPI) -> AsyncGenerator[None, None]:
app.state.recommended_question_store = make_recommended_question_store(sf)
from deerflow.persistence.tags import make_tag_store
app.state.tag_store = make_tag_store(sf)
# Run event store (has its own factory with config-driven backend selection)
run_events_config = getattr(config, "run_events", None)
app.state.run_event_store = make_run_event_store(run_events_config)
@@ -209,6 +214,14 @@ def get_notification_store(request: Request) -> NotificationStore:
return val
def get_tag_store(request: Request) -> TagStore:
"""Return the tag store."""
val = getattr(request.app.state, "tag_store", None)
if val is None:
raise HTTPException(status_code=503, detail="Tag store not available")
return val
def get_run_context(request: Request) -> RunContext:
"""Build a :class:`RunContext` from ``app.state`` singletons.
@@ -9,14 +9,15 @@ from typing import Any
from uuid import uuid4
import yaml
from fastapi import APIRouter, HTTPException, Request
from fastapi import APIRouter, HTTPException, Query, Request
from pydantic import BaseModel, Field
from app.gateway.deps import get_agent_store
from app.gateway.deps import get_agent_store, get_tag_store
from deerflow.config.agents_api_config import get_agents_api_config
from deerflow.config.agents_config import list_custom_agents, load_agent_config, load_agent_soul, validate_agent_id
from deerflow.config.paths import get_paths
from deerflow.persistence.agents import AgentStore
from deerflow.persistence.tags import TagStore
from deerflow.runtime.user_context import get_effective_user_id
logger = logging.getLogger(__name__)
@@ -42,6 +43,8 @@ class AgentResponse(BaseModel):
tool_groups: list[str] | None = None
skills: list[str] | None = None
tags: list[dict] = Field(default_factory=list, description="Tags assigned to this agent")
class AgentsListResponse(BaseModel):
"""Response model for listing all visible agents."""
@@ -238,15 +241,30 @@ async def _get_editable_or_raise(
summary="List Agents",
description="List built-in agents, the current user's agents, and published agents.",
)
async def list_agents(request: Request) -> AgentsListResponse:
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"),
) -> AgentsListResponse:
_require_agents_api_enabled()
try:
store = get_agent_store(request)
tag_store: TagStore = get_tag_store(request)
await _sync_legacy_agents(store)
user_id = _current_user_id(request)
agents = await store.list_visible(user_id)
return AgentsListResponse(agents=[_record_to_response(a, include_soul=True) for a in agents])
responses = [_record_to_response(a, include_soul=True) for a in agents]
assignments = await tag_store.list_assignments("agent", [r.id for r in responses])
for resp in responses:
resp.tags = assignments.get(resp.id, [])
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)]
return AgentsListResponse(agents=responses)
except HTTPException:
raise
except Exception as e:
@@ -485,6 +503,10 @@ async def delete_agent(agent_id: str, request: Request) -> None:
agent_dir = get_paths().agent_dir(agent_id)
if agent_dir.exists():
shutil.rmtree(agent_dir)
try:
await get_tag_store(request).unassign_all("agent", agent_id)
except Exception: # noqa: BLE001 — tag cleanup must not block deletion
pass
logger.info("Deleted agent '%s' from %s", agent_id, agent_dir)
except HTTPException:
raise
@@ -10,11 +10,11 @@ from pathlib import Path
from typing import Any
from urllib.parse import quote
from fastapi import APIRouter, HTTPException, Request
from fastapi import APIRouter, HTTPException, Query, Request
from fastapi.responses import FileResponse, Response, StreamingResponse
from pydantic import BaseModel, Field
from app.gateway.deps import get_current_user, get_local_provider
from app.gateway.deps import get_current_user, get_local_provider, get_tag_store
from deerflow.runtime.scheduler import get_scheduled_task_service
router = APIRouter(prefix="/api/scheduled-tasks", tags=["scheduled-tasks"])
@@ -174,11 +174,25 @@ async def get_scheduler_thread(request: Request) -> dict:
@router.get("")
async def list_scheduled_tasks(request: Request) -> list[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"),
) -> list[dict]:
service = get_scheduled_task_service()
user_id = await _user_id(request)
tasks = await service.list_tasks(user_id)
await _enrich_with_creator(tasks)
tag_store = get_tag_store(request)
assignments = await tag_store.list_assignments("scheduled_task", [str(t.get("task_id")) for t in tasks])
for task in tasks:
task["tags"] = assignments.get(str(task.get("task_id")), [])
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", []))]
return tasks
@@ -378,6 +392,10 @@ async def delete_scheduled_task(task_id: str, request: Request) -> dict:
deleted = await service.delete_task(user_id, task_id)
if not deleted:
raise HTTPException(status_code=404, detail=f"Task {task_id} not found")
try:
await get_tag_store(request).unassign_all("scheduled_task", task_id)
except Exception: # noqa: BLE001 — tag cleanup must not block deletion
pass
return {"success": True}
@@ -5,15 +5,16 @@ from datetime import datetime
from pathlib import Path
from typing import Any
from fastapi import APIRouter, Body, Depends, File, HTTPException, Request, UploadFile
from fastapi import APIRouter, Body, Depends, File, HTTPException, Query, Request, UploadFile
from pydantic import BaseModel, Field
from app.gateway.deps import get_agent_store, get_config, get_skill_store
from app.gateway.deps import get_agent_store, get_config, get_skill_store, get_tag_store
from app.gateway.path_utils import resolve_thread_virtual_path
from deerflow.agents.lead_agent.prompt import refresh_skills_system_prompt_cache_async
from deerflow.config.app_config import AppConfig
from deerflow.config.extensions_config import ExtensionsConfig, SkillStateConfig, get_extensions_config, reload_extensions_config
from deerflow.persistence.skills import SkillStore
from deerflow.persistence.tags import TagStore
from deerflow.runtime.user_context import get_effective_user_id
from deerflow.skills import Skill
from deerflow.skills.cascade import cascade_skill_unpublished_or_deleted
@@ -95,6 +96,7 @@ class SkillResponse(BaseModel):
owner_user_id: str | None = Field(default=None, description="Custom skill owner (null = built-in or legacy)")
published: bool = Field(default=False, description="Whether the owner has made this skill visible to other users")
builtin: bool = Field(default=False, description="True when owner_user_id is null (no human owner)")
tags: list[dict] = Field(default_factory=list, description="Tags assigned to this skill")
class SkillsListResponse(BaseModel):
@@ -208,6 +210,24 @@ async def _build_ownership_index(skill_store: SkillStore, user_id: str) -> dict[
return {record["name"]: record for record in records}
async def _attach_and_filter_tags(
tag_store: TagStore,
responses: list[SkillResponse],
search: str | None,
tag_id: 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])
for resp in responses:
resp.tags = assignments.get(resp.name, [])
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)]
return responses
@router.get(
"/skills",
response_model=SkillsListResponse,
@@ -218,6 +238,9 @@ async def list_skills(
request: Request,
config: AppConfig = Depends(get_config),
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"),
) -> SkillsListResponse:
try:
user_id = _current_user_id(request)
@@ -234,6 +257,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)
return SkillsListResponse(skills=responses)
except Exception as e:
logger.error(f"Failed to load skills: {e}", exc_info=True)
@@ -553,6 +577,11 @@ async def delete_custom_skill(
else:
await skill_store.delete(skill_name, user_id)
try:
await get_tag_store(request).unassign_all("skill", skill_name)
except Exception: # noqa: BLE001 — tag cleanup must not block deletion
pass
# Strip references from every agent that pulled this skill in,
# and notify their owners (no-op for self).
await cascade_skill_unpublished_or_deleted(
@@ -0,0 +1,212 @@
"""Tag management API.
Tags are split into three types (``agent`` / ``skill`` / ``scheduled_task``).
A tag may only be applied to a resource of its own type. Tag CRUD and tag
assignment are admin-only; listing tags and reading a resource's tags is open
to everyone (the frontend needs them to render chips and search filters).
"""
from __future__ import annotations
import logging
import uuid
from fastapi import APIRouter, Depends, HTTPException, Query, Request
from pydantic import BaseModel, Field
from app.gateway.deps import get_optional_user_from_request, get_tag_store
from deerflow.persistence.tags import TAG_TYPES, TagStore
logger = logging.getLogger(__name__)
router = APIRouter(prefix="/api/tags", tags=["tags"])
# --------------------------------------------------------------------------- auth
async def _require_admin(request: Request) -> None:
"""Reject non-admins. Lets the call through when auth is disabled."""
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="Tag management is admin-only")
def _validate_tag_type(tag_type: str) -> str:
if tag_type not in TAG_TYPES:
raise HTTPException(status_code=422, detail=f"Invalid tag type '{tag_type}'. Allowed: {', '.join(TAG_TYPES)}")
return tag_type
# ------------------------------------------------------------------- schemas
class TagResponse(BaseModel):
id: str
name: str
tag_type: str
color: str = "gray"
description: str = ""
usage_count: int = 0
created_at: str | None = None
updated_at: str | None = None
class TagListResponse(BaseModel):
tags: list[TagResponse]
class TagCreateRequest(BaseModel):
name: str = Field(..., min_length=1, max_length=256)
tag_type: str = Field(..., description="One of: agent, skill, scheduled_task")
color: str = Field(default="gray", max_length=16)
description: str = Field(default="", max_length=1024)
class TagUpdateRequest(BaseModel):
name: str | None = Field(default=None, min_length=1, max_length=256)
color: str | None = Field(default=None, max_length=16)
description: str | None = Field(default=None, max_length=1024)
class TagAssignmentRequest(BaseModel):
tag_ids: list[str] = Field(default_factory=list, description="Full set of tag ids to assign; replaces the existing set")
# ----------------------------------------------------------------- tag CRUD
@router.get("", response_model=TagListResponse, summary="List Tags")
async def list_tags(
tag_type: str | None = Query(default=None, description="Filter by tag type"),
store: TagStore = Depends(get_tag_store),
) -> TagListResponse:
if tag_type is not None:
_validate_tag_type(tag_type)
try:
records = await store.list_tags(tag_type)
return TagListResponse(tags=[TagResponse(**r) for r in records])
except Exception as e:
logger.error("Failed to list tags: %s", e, exc_info=True)
raise HTTPException(status_code=500, detail=f"Failed to list tags: {e}")
@router.post("", response_model=TagResponse, status_code=201, summary="Create Tag")
async def create_tag(
body: TagCreateRequest,
request: Request,
store: TagStore = Depends(get_tag_store),
) -> TagResponse:
await _require_admin(request)
_validate_tag_type(body.tag_type)
try:
record = await store.create_tag(
{
"id": uuid.uuid4().hex,
"name": body.name.strip(),
"tag_type": body.tag_type,
"color": body.color,
"description": body.description,
}
)
return TagResponse(**record)
except ValueError as e:
raise HTTPException(status_code=409, detail=str(e))
except HTTPException:
raise
except Exception as e:
logger.error("Failed to create tag: %s", e, exc_info=True)
raise HTTPException(status_code=500, detail=f"Failed to create tag: {e}")
@router.put("/{tag_id}", response_model=TagResponse, summary="Update Tag")
async def update_tag(
tag_id: str,
body: TagUpdateRequest,
request: Request,
store: TagStore = Depends(get_tag_store),
) -> TagResponse:
await _require_admin(request)
update_data = body.model_dump(exclude_unset=True)
if "name" in update_data and update_data["name"] is not None:
update_data["name"] = update_data["name"].strip()
try:
record = await store.update_tag(tag_id, update_data)
if record is None:
raise HTTPException(status_code=404, detail=f"Tag '{tag_id}' not found")
return TagResponse(**record)
except ValueError as e:
raise HTTPException(status_code=409, detail=str(e))
except HTTPException:
raise
except Exception as e:
logger.error("Failed to update tag: %s", e, exc_info=True)
raise HTTPException(status_code=500, detail=f"Failed to update tag: {e}")
@router.delete("/{tag_id}", status_code=204, summary="Delete Tag")
async def delete_tag(
tag_id: str,
request: Request,
store: TagStore = Depends(get_tag_store),
) -> None:
await _require_admin(request)
try:
deleted = await store.delete_tag(tag_id)
if not deleted:
raise HTTPException(status_code=404, detail=f"Tag '{tag_id}' not found")
except HTTPException:
raise
except Exception as e:
logger.error("Failed to delete tag: %s", e, exc_info=True)
raise HTTPException(status_code=500, detail=f"Failed to delete tag: {e}")
# --------------------------------------------------------------- assignments
@router.get(
"/assignments/{target_type}/{target_id}",
response_model=TagListResponse,
summary="Get Resource Tags",
)
async def get_resource_tags(
target_type: str,
target_id: str,
store: TagStore = Depends(get_tag_store),
) -> TagListResponse:
_validate_tag_type(target_type)
try:
records = await store.get_target_tags(target_type, target_id)
return TagListResponse(tags=[TagResponse(**r) for r in records])
except Exception as e:
logger.error("Failed to get resource tags: %s", e, exc_info=True)
raise HTTPException(status_code=500, detail=f"Failed to get resource tags: {e}")
@router.put(
"/assignments/{target_type}/{target_id}",
response_model=TagListResponse,
summary="Set Resource Tags",
)
async def set_resource_tags(
target_type: str,
target_id: str,
body: TagAssignmentRequest,
request: Request,
store: TagStore = Depends(get_tag_store),
) -> TagListResponse:
await _require_admin(request)
_validate_tag_type(target_type)
try:
records = await store.set_target_tags(target_type, target_id, body.tag_ids)
return TagListResponse(tags=[TagResponse(**r) for r in records])
except ValueError as e:
raise HTTPException(status_code=422, detail=str(e))
except HTTPException:
raise
except Exception as e:
logger.error("Failed to set resource tags: %s", e, exc_info=True)
raise HTTPException(status_code=500, detail=f"Failed to set resource tags: {e}")
@@ -100,12 +100,15 @@ _DEFAULT_ASSISTANT_ID = "lead_agent"
def _prepend_prompt_prefix(graph_input: dict[str, Any], prefix: str) -> dict[str, Any]:
"""Return ``graph_input`` with the prefix prepended to its first HumanMessage.
"""Return ``graph_input`` with the prefix *tagged* onto its first HumanMessage.
The prefix is stored in ``additional_kwargs['prompt_prefix']`` rather than
concatenated into ``content``. This keeps the persisted/displayed message
clean — the user never sees the prefix — while ``PromptPrefixMiddleware``
injects it into the content of the request actually sent to the LLM.
Leaves the input unchanged when there are no messages or the first message
is not a human turn. Idempotent in the sense that it only touches the first
human message, so re-running this with the same prefix would double-prepend
— callers must gate it on first-turn detection.
is not a human turn.
"""
if not prefix:
return graph_input
@@ -115,14 +118,9 @@ def _prepend_prompt_prefix(graph_input: dict[str, Any], prefix: str) -> dict[str
new_messages = list(messages)
for idx, msg in enumerate(new_messages):
if isinstance(msg, HumanMessage):
existing = msg.content
if isinstance(existing, str):
new_messages[idx] = HumanMessage(content=f"{prefix}\n\n{existing}".strip("\n"))
elif isinstance(existing, list):
# Structured content (text blocks + media). Prepend a new text block.
new_messages[idx] = HumanMessage(content=[{"type": "text", "text": prefix}, *existing])
else:
new_messages[idx] = HumanMessage(content=f"{prefix}\n\n{existing!s}")
extra = dict(getattr(msg, "additional_kwargs", None) or {})
extra["prompt_prefix"] = prefix
new_messages[idx] = msg.model_copy(update={"additional_kwargs": extra})
break
return {**graph_input, "messages": new_messages}
@@ -380,7 +378,6 @@ async def start_run(
# Upsert thread metadata so the thread appears in /threads/search,
# even for threads that were never explicitly created via POST /threads
# (e.g. stateless runs).
thread_existed = False
try:
existing = await run_ctx.thread_store.get(thread_id)
if existing is None:
@@ -390,7 +387,6 @@ async def start_run(
metadata=body.metadata,
)
else:
thread_existed = True
await run_ctx.thread_store.update_status(thread_id, "running")
except Exception:
logger.warning("Failed to upsert thread_meta for %s (non-fatal)", sanitize_log_param(thread_id))
@@ -398,13 +394,15 @@ async def start_run(
agent_factory = resolve_agent_factory(body.assistant_id)
graph_input = normalize_input(body.input)
# Server-side safety net for the admin-configurable prompt prefix: when the
# caller opted in via context.prompt_prefix_enabled AND this is the very
# first turn of the thread, prepend the configured prefix to the human
# message. We deliberately skip already-running threads so the prefix is
# never inserted twice — the frontend toggle is a per-message hint, but
# this check is what makes the feature safe against client bugs / replays.
if not thread_existed and _prompt_prefix_opted_in(body):
# Admin-configurable prompt prefix: when the caller opted in via
# context.prompt_prefix_enabled, tag the human message with the configured
# prefix (stored in additional_kwargs, not concatenated into content, so the
# user never sees it — PromptPrefixMiddleware injects it for the LLM only).
# The frontend only sends the flag on the opening turn, so this naturally
# applies once. We intentionally do NOT gate on thread-row existence: the
# thread_meta row is frequently pre-created, which previously skipped the
# prefix for genuine first turns.
if _prompt_prefix_opted_in(body):
prefix_settings = load_system_settings().prompt_prefix
if prefix_settings.enabled and prefix_settings.prompt_prefix.strip():
graph_input = _prepend_prompt_prefix(graph_input, prefix_settings.prompt_prefix.strip())