feat: 支持智能体置顶配置

offline-backend-20260512/backend/app/gateway/routers/agents.py

@@ -15,7 +15,7 @@ from fastapi import APIRouter, Depends, HTTPException, Query, Request
 from pydantic import BaseModel, Field
 
 from app.gateway.auth.password import verify_password_async
-from app.gateway.deps import get_agent_store, get_config, get_tag_store
+from app.gateway.deps import get_agent_store, get_config, get_tag_store
 from deerflow.agents.lead_agent.prompt import refresh_skills_system_prompt_cache_async
 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
@@ -62,10 +62,15 @@ class AgentResponse(BaseModel):
     is_favorite: bool = Field(
         default=False,
         description="Whether the requesting user has favorited (收藏) this agent.",
-    )
-
-
-class AgentsListResponse(BaseModel):
+    )
+
+    is_pinned: bool = Field(
+        default=False,
+        description="Whether the requesting user has pinned this agent.",
+    )
+
+
+class AgentsListResponse(BaseModel):
     """Response model for listing agents.
 
     ``total`` / ``page`` / ``page_size`` describe server-side pagination. When
@@ -110,7 +115,7 @@ class AgentUpdateRequest(BaseModel):
     tool_groups: list[str] | None = Field(default=None, description="Updated tool group whitelist (config.yaml)")
 
 
-class AgentSelectorResponse(BaseModel):
+class AgentSelectorResponse(BaseModel):
     """Response for the homepage agent selector dropdown.
 
     The list is fully curated by admins (``featured_order`` on each row).
@@ -120,10 +125,10 @@ class AgentSelectorResponse(BaseModel):
     agents: list[AgentResponse] = Field(
         default_factory=list,
         description="Admin-curated agents, sorted by featured_order ascending.",
-    )
-
-
-class AgentFeaturedRequest(BaseModel):
+    )
+
+
+class AgentFeaturedRequest(BaseModel):
     """Request body for setting/clearing an agent's homepage featured rank."""
 
     order: int | None = Field(
@@ -343,7 +348,7 @@ def _ensure_agent_dir_from_record(record: dict[str, Any]) -> None:
         logger.exception("Failed to self-heal agent dir for '%s'", agent_id)
 
 
-def _record_to_response(
+def _record_to_response(
     record: dict[str, Any],
     *,
     include_soul: bool = False,
@@ -385,10 +390,21 @@ def _record_to_response(
         tool_groups=extras["tool_groups"],
         skills=extras["skills"],
         featured_order=record.get("featured_order"),
-    )
-
-
-async def _record_to_response_async(
+    )
+
+
+def _sort_agent_responses(responses: list[AgentResponse], sort: str) -> list[AgentResponse]:
+    reverse = sort not in {"time_asc", "updated_asc", "name_asc"}
+    if sort in {"name_asc", "name_desc"}:
+        ordered = sorted(responses, key=lambda r: (r.name or "").lower(), reverse=reverse)
+    elif sort in {"updated_desc", "updated_asc"}:
+        ordered = sorted(responses, key=lambda r: str(r.updated_at or ""), reverse=reverse)
+    else:
+        ordered = sorted(responses, key=lambda r: str(r.created_at or ""), reverse=reverse)
+    return sorted(ordered, key=lambda r: 0 if r.is_pinned else 1)
+
+
+async def _record_to_response_async(
     record: dict[str, Any],
     *,
     include_soul: bool = False,
@@ -462,18 +478,20 @@ async def _build_list_responses(
         _record_to_response(a, include_soul=False, include_extras=False) for a in records
     ]
     ids = [r.id for r in responses]
-    extras = await store.get_extras_for(ids)
-    assignments = await tag_store.list_assignments("agent", ids)
-    favorite_ids = await store.list_favorite_ids(user_id)
-    for resp in responses:
+    extras = await store.get_extras_for(ids)
+    assignments = await tag_store.list_assignments("agent", ids)
+    favorite_ids = await store.list_favorite_ids(user_id)
+    pin_ids = await store.list_pin_ids(user_id)
+    for resp in responses:
         cached = extras.get(resp.id)
         if cached is not None:
             resp.skills = cached.get("skills")
             resp.tool_groups = cached.get("tool_groups")
             resp.model = cached.get("model")
-        resp.tags = assignments.get(resp.id, [])
-        resp.is_favorite = resp.id in favorite_ids
-    return responses
+        resp.tags = assignments.get(resp.id, [])
+        resp.is_favorite = resp.id in favorite_ids
+        resp.is_pinned = resp.id in pin_ids
+    return responses
 
 
 @router.get(
@@ -491,9 +509,14 @@ async def list_agents(
         pattern="^(mine|square)$",
         description="Pagination scope. 'mine' = owned + favorited; 'square' = built-in/published public. Omit for the default combined visibility list.",
     ),
-    page: int | None = Query(default=None, ge=1, description="1-based page index. Providing this (or 'scope') enables server-side pagination."),
-    page_size: int = Query(default=20, ge=1, le=200, description="Items per page when paginating."),
-    admin: bool = Query(
+    page: int | None = Query(default=None, ge=1, description="1-based page index. Providing this (or 'scope') enables server-side pagination."),
+    page_size: int = Query(default=20, ge=1, le=200, description="Items per page when paginating."),
+    sort: str = Query(
+        default="time_desc",
+        pattern="^(time_desc|time_asc|updated_desc|updated_asc|name_asc|name_desc)$",
+        description="Sort order. Default is newest created first.",
+    ),
+    admin: bool = Query(
         default=False,
         description=(
             "Admin-only override. When ``true`` and the caller is a system admin, "
@@ -520,10 +543,11 @@ async def list_agents(
                 scope=scope,
                 search=search,
                 tag_ids=tag_ids,
-                page=eff_page,
-                page_size=page_size,
-                admin=admin,
-            )
+                page=eff_page,
+                page_size=page_size,
+                admin=admin,
+                sort=sort,
+            )
             responses = await _build_list_responses(store, tag_store, user_id, rows)
             return AgentsListResponse(agents=responses, total=total, page=eff_page, page_size=page_size)
 
@@ -535,10 +559,11 @@ async def list_agents(
         if search:
             needle = search.strip().lower()
             responses = [r for r in responses if needle in r.name.lower()]
-        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, total=len(responses), page=1, page_size=len(responses))
+        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)]
+        responses = _sort_agent_responses(responses, sort)
+        return AgentsListResponse(agents=responses, total=len(responses), page=1, page_size=len(responses))
     except HTTPException:
         raise
     except Exception as e:
@@ -551,14 +576,14 @@ async def list_agents(
     summary="Check Agent Name",
     description="Validate an agent display name. Duplicate names are allowed.",
 )
-async def check_agent_name(name: str) -> dict[str, Any]:
-    _require_agents_api_enabled()
-    normalized = _validate_display_name(name)
-    return {"available": True, "name": normalized}
-
-
-@router.get(
-    "/agents/selector",
+async def check_agent_name(name: str) -> dict[str, Any]:
+    _require_agents_api_enabled()
+    normalized = _validate_display_name(name)
+    return {"available": True, "name": normalized}
+
+
+@router.get(
+    "/agents/selector",
     response_model=AgentSelectorResponse,
     summary="Agent Homepage Selector",
     description=(
@@ -610,10 +635,12 @@ async def get_agent(agent_id: str, request: Request) -> AgentResponse:
         # Detail view legitimately reads SOUL.md + config.yaml — hop to a
         # worker thread so the asyncio loop stays responsive under concurrent
         # detail fetches.
-        response = await _record_to_response_async(record, include_soul=True, include_extras=True)
-        favorite_ids = await store.list_favorite_ids(user_id)
-        response.is_favorite = agent_id in favorite_ids
-        return response
+        response = await _record_to_response_async(record, include_soul=True, include_extras=True)
+        favorite_ids = await store.list_favorite_ids(user_id)
+        pin_ids = await store.list_pin_ids(user_id)
+        response.is_favorite = agent_id in favorite_ids
+        response.is_pinned = agent_id in pin_ids
+        return response
     except HTTPException:
         raise
     except Exception as e:
@@ -847,12 +874,16 @@ async def delete_agent(agent_id: str, request: Request) -> None:
             await get_tag_store(request).unassign_all("agent", agent_id)
         except Exception:  # noqa: BLE001 — tag cleanup must not block deletion
             pass
-        try:
-            await store.delete_favorites_for_agent(agent_id)
-        except Exception:  # noqa: BLE001 — favorite cleanup must not block deletion
-            pass
-        try:
-            await store.delete_extras_for_agent(agent_id)
+        try:
+            await store.delete_favorites_for_agent(agent_id)
+        except Exception:  # noqa: BLE001 — favorite cleanup must not block deletion
+            pass
+        try:
+            await store.delete_pins_for_agent(agent_id)
+        except Exception:  # noqa: BLE001 - pin cleanup must not block deletion
+            pass
+        try:
+            await store.delete_extras_for_agent(agent_id)
         except Exception:  # noqa: BLE001 — cache cleanup must not block deletion
             pass
         logger.info("Deleted agent '%s' from %s", agent_id, agent_dir)
@@ -894,7 +925,7 @@ async def favorite_agent(agent_id: str, request: Request) -> None:
     summary="Unfavorite Agent",
     description="Remove an agent from the current user's favorites. No-op when not favorited.",
 )
-async def unfavorite_agent(agent_id: str, request: Request) -> None:
+async def unfavorite_agent(agent_id: str, request: Request) -> None:
     _require_agents_api_enabled()
     agent_id = _validate_storage_id(agent_id)
 
@@ -905,13 +936,60 @@ async def unfavorite_agent(agent_id: str, request: Request) -> None:
         logger.info("User '%s' unfavorited agent '%s'", user_id, agent_id)
     except HTTPException:
         raise
-    except Exception as e:
-        logger.error("Failed to unfavorite agent '%s': %s", agent_id, e, exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to unfavorite agent: {str(e)}") from e
-
-
-@router.put(
-    "/agents/{agent_id}/featured",
+    except Exception as e:
+        logger.error("Failed to unfavorite agent '%s': %s", agent_id, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to unfavorite agent: {str(e)}") from e
+
+
+@router.post(
+    "/agents/{agent_id}/pin",
+    status_code=204,
+    summary="Pin Agent",
+    description="Pin a visible agent to the top of the current user's lists. Idempotent.",
+)
+async def pin_agent(agent_id: str, request: Request) -> None:
+    _require_agents_api_enabled()
+    agent_id = _validate_storage_id(agent_id)
+
+    try:
+        store = get_agent_store(request)
+        user_id = _current_user_id(request)
+        record = await store.get_visible(agent_id, user_id)
+        if record is None:
+            raise HTTPException(status_code=404, detail=f"Agent '{agent_id}' not found")
+        await store.add_pin(user_id, agent_id)
+        logger.info("User '%s' pinned agent '%s'", user_id, agent_id)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to pin agent '%s': %s", agent_id, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to pin agent: {str(e)}") from e
+
+
+@router.delete(
+    "/agents/{agent_id}/pin",
+    status_code=204,
+    summary="Unpin Agent",
+    description="Remove the current user's pin from an agent. No-op when not pinned.",
+)
+async def unpin_agent(agent_id: str, request: Request) -> None:
+    _require_agents_api_enabled()
+    agent_id = _validate_storage_id(agent_id)
+
+    try:
+        store = get_agent_store(request)
+        user_id = _current_user_id(request)
+        await store.remove_pin(user_id, agent_id)
+        logger.info("User '%s' unpinned agent '%s'", user_id, agent_id)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to unpin agent '%s': %s", agent_id, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to unpin agent: {str(e)}") from e
+
+
+@router.put(
+    "/agents/{agent_id}/featured",
     response_model=AgentResponse,
     summary="Set Agent Featured Rank (admin)",
     description=(
@@ -953,14 +1031,19 @@ async def set_agent_featured(
         raise HTTPException(status_code=500, detail=f"Failed to set featured: {str(e)}") from e
 
 
-class PrivateSquareListRequest(BaseModel):
+class PrivateSquareListRequest(BaseModel):
     """Request body for listing all private-square agents."""
 
     password: str = Field(..., description="Plain-text private-square password. Verified against the admin-configured hash before the listing is returned.")
     search: str | None = Field(default=None, description="Case-insensitive fuzzy match on agent name (raw or desensitized).")
     tag_ids: list[str] | None = Field(default=None, description="Keep agents carrying any of these tags (OR).")
-    page: int | None = Field(default=None, ge=1, description="1-based page index. Providing this enables server-side pagination.")
-    page_size: int = Field(default=20, ge=1, le=200, description="Items per page when paginating.")
+    page: int | None = Field(default=None, ge=1, description="1-based page index. Providing this enables server-side pagination.")
+    page_size: int = Field(default=20, ge=1, le=200, description="Items per page when paginating.")
+    sort: str = Field(
+        default="time_desc",
+        pattern="^(time_desc|time_asc|updated_desc|updated_asc|name_asc|name_desc)$",
+        description="Sort order. Default is newest created first.",
+    )
 
 
 class AgentPrivateUpdateRequest(BaseModel):
@@ -1003,15 +1086,17 @@ async def list_private_square(body: PrivateSquareListRequest, request: Request)
                 scope="private",
                 search=body.search,
                 tag_ids=body.tag_ids,
-                page=body.page,
-                page_size=body.page_size,
-            )
+                page=body.page,
+                page_size=body.page_size,
+                sort=body.sort,
+            )
             responses = await _build_list_responses(store, tag_store, user_id, rows)
             return AgentsListResponse(agents=responses, total=total, page=body.page, page_size=body.page_size)
 
         records = await store.list_private()
-        responses = await _build_list_responses(store, tag_store, user_id, records)
-        return AgentsListResponse(agents=responses, total=len(responses), page=1, page_size=len(responses))
+        responses = await _build_list_responses(store, tag_store, user_id, records)
+        responses = _sort_agent_responses(responses, body.sort)
+        return AgentsListResponse(agents=responses, total=len(responses), page=1, page_size=len(responses))
     except HTTPException:
         raise
     except Exception as e:

offline-backend-20260512/backend/app/gateway/routers/skills.py

@@ -7,7 +7,7 @@ import re
 import subprocess
 import sys
 import tempfile
-from datetime import datetime
+from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any
 
@@ -119,6 +119,7 @@ class SkillResponse(BaseModel):
     view_count: int = Field(default=0, description="Number of times the skill has been viewed")
     patch_count: int = Field(default=0, description="Number of times the skill has been patched")
     last_activity_at: datetime | None = Field(default=None, description="Most recent activity timestamp")
+    created_at: datetime | None = Field(default=None, description="Skill creation timestamp when known")
     state: str = Field(default="active", description="Lifecycle state: active, stale, or archived")
     pinned: bool = Field(default=False, description="Whether this skill is pinned (excluded from curation)")
     source: str = Field(default="upload", description="Origin: 'agent' for agent-created, 'upload' for user-uploaded")
@@ -241,8 +242,20 @@ def _skill_to_response(
     from deerflow.skills.usage import get_entry, latest_activity_at
 
     entry = get_entry(skill.name)
+    created_at_str = entry.get("created_at")
     last_at_str = latest_activity_at(skill.name)
+    created_at: datetime | None = None
     last_at: datetime | None = None
+    if created_at_str:
+        try:
+            created_at = datetime.fromisoformat(created_at_str)
+        except Exception:
+            pass
+    if created_at is None:
+        try:
+            created_at = datetime.fromtimestamp(skill.skill_file.stat().st_mtime, tz=UTC)
+        except Exception:
+            pass
     if last_at_str:
         try:
             last_at = datetime.fromisoformat(last_at_str)
@@ -278,6 +291,7 @@ def _skill_to_response(
         view_count=entry.get("view_count", 0),
         patch_count=entry.get("patch_count", 0),
         last_activity_at=last_at,
+        created_at=created_at,
         state=entry.get("state", "active"),
         pinned=entry.get("pinned", False),
         source=entry.get("source", "upload"),
@@ -688,6 +702,17 @@ async def _attach_and_filter_tags(
     return responses
 
 
+def _sort_skill_responses(responses: list[SkillResponse], sort: str) -> list[SkillResponse]:
+    reverse = sort not in {"time_asc", "activity_asc", "name_asc", "usage_asc"}
+    if sort in {"name_asc", "name_desc"}:
+        return sorted(responses, key=lambda r: (r.name or "").lower(), reverse=reverse)
+    if sort in {"usage_desc", "usage_asc"}:
+        return sorted(responses, key=lambda r: int(r.use_count or 0), reverse=reverse)
+    if sort in {"activity_desc", "activity_asc"}:
+        return sorted(responses, key=lambda r: str(r.last_activity_at or r.created_at or ""), reverse=reverse)
+    return sorted(responses, key=lambda r: str(r.created_at or r.last_activity_at or ""), reverse=reverse)
+
+
 @router.get(
     "/skills",
     response_model=SkillsListResponse,
@@ -701,6 +726,11 @@ async def list_skills(
     tag_store: TagStore = Depends(get_tag_store),
     search: str | None = Query(default=None, description="Case-insensitive fuzzy match on skill name"),
     tag_ids: list[str] | None = Query(default=None, description="Keep skills carrying any of these tags (OR)"),
+    sort: str = Query(
+        default="time_desc",
+        pattern="^(time_desc|time_asc|activity_desc|activity_asc|usage_desc|usage_asc|name_asc|name_desc)$",
+        description="Sort order. Default is newest created/modified first.",
+    ),
     admin: bool = Query(
         default=False,
         description=(
@@ -754,6 +784,7 @@ async def list_skills(
                 )
             )
         responses = await _attach_and_filter_tags(tag_store, responses, search, tag_ids)
+        responses = _sort_skill_responses(responses, sort)
         return SkillsListResponse(skills=responses)
     except HTTPException:
         raise

offline-backend-20260512/backend/packages/harness/deerflow/persistence/agents/base.py

@@ -119,17 +119,18 @@ class AgentStore(ABC):
         raise NotImplementedError
 
     @abstractmethod
-    async def list_paginated(
-        self,
-        *,
-        user_id: str,
-        scope: str | None,
-        search: str | None,
-        tag_ids: list[str] | None,
-        page: int,
-        page_size: int,
-        admin: bool = False,
-    ) -> tuple[list[dict[str, Any]], int]:
+    async def list_paginated(
+        self,
+        *,
+        user_id: str,
+        scope: str | None,
+        search: str | None,
+        tag_ids: list[str] | None,
+        page: int,
+        page_size: int,
+        admin: bool = False,
+        sort: str = "time_desc",
+    ) -> tuple[list[dict[str, Any]], int]:
         """Return one page of agents plus the total matching count.
 
         ``scope``:
@@ -145,9 +146,9 @@ class AgentStore(ABC):
         the COUNT, and LIMIT/OFFSET all execute in SQL.
 
         Returns ``(rows, total)`` where ``rows`` is at most ``page_size`` items
-        for the 1-based ``page``.
-        """
-        raise NotImplementedError
+        for the 1-based ``page``.
+        """
+        raise NotImplementedError
 
     # --- Listing cache (skills / tool_groups / model) ---
 
@@ -198,6 +199,28 @@ class AgentStore(ABC):
         raise NotImplementedError
 
     @abstractmethod
-    async def delete_favorites_for_agent(self, agent_id: str) -> None:
-        """Drop every user's favorite of ``agent_id`` (called on agent delete)."""
-        raise NotImplementedError
+    async def delete_favorites_for_agent(self, agent_id: str) -> None:
+        """Drop every user's favorite of ``agent_id`` (called on agent delete)."""
+        raise NotImplementedError
+
+    # --- Per-user pins ("置顶") ---
+
+    @abstractmethod
+    async def add_pin(self, user_id: str, agent_id: str) -> None:
+        """Pin ``agent_id`` for ``user_id``. Idempotent."""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def remove_pin(self, user_id: str, agent_id: str) -> bool:
+        """Remove a per-user pin. Returns ``False`` when none existed."""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def list_pin_ids(self, user_id: str) -> set[str]:
+        """Return the set of agent ids pinned by ``user_id``."""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def delete_pins_for_agent(self, agent_id: str) -> None:
+        """Drop every user's pin of ``agent_id`` (called on agent delete)."""
+        raise NotImplementedError

offline-backend-20260512/backend/packages/harness/deerflow/persistence/agents/memory.py

@@ -21,8 +21,9 @@ def _copy(data: dict[str, Any]) -> dict[str, Any]:
 
 class MemoryAgentStore(AgentStore):
     def __init__(self) -> None:
-        self._agents: dict[str, dict[str, Any]] = {}
-        self._favorites: set[tuple[str, str]] = set()
+        self._agents: dict[str, dict[str, Any]] = {}
+        self._favorites: set[tuple[str, str]] = set()
+        self._pins: set[tuple[str, str]] = set()
         # Listing cache mirrors (see AgentExtrasRow / AgentSkillRow):
         self._skills: dict[str, list[str]] = {}
         self._extras: dict[str, dict[str, Any]] = {}
@@ -185,17 +186,18 @@ class MemoryAgentStore(AgentStore):
             return bool(agent.get("is_private"))
         return self._is_visible(agent, user_id)
 
-    async def list_paginated(
-        self,
-        *,
-        user_id: str,
-        scope: str | None,
+    async def list_paginated(
+        self,
+        *,
+        user_id: str,
+        scope: str | None,
         search: str | None,
-        tag_ids: list[str] | None,
-        page: int,
-        page_size: int,
-        admin: bool = False,
-    ) -> tuple[list[dict[str, Any]], int]:
+        tag_ids: list[str] | None,
+        page: int,
+        page_size: int,
+        admin: bool = False,
+        sort: str = "time_desc",
+    ) -> tuple[list[dict[str, Any]], int]:
         # NOTE: the in-memory store has no tag-assignment data, so ``tag_ids``
         # is ignored here. Tag-filter behavior is covered by the SQL repo tests.
         matched = [
@@ -204,9 +206,31 @@ class MemoryAgentStore(AgentStore):
             if self._matches_scope(a, user_id=user_id, scope=scope, admin=admin)
             and (not search or not search.strip() or name_matches(a.get("name") or "", search))
         ]
-        matched.sort(key=lambda a: (a.get("created_at") or "", a.get("id") or ""))
-        total = len(matched)
-        start = max(page - 1, 0) * page_size
+        if sort == "time_asc":
+            matched.sort(key=lambda a: (a.get("created_at") or "", a.get("id") or ""))
+        elif sort == "updated_desc":
+            matched.sort(
+                key=lambda a: (a.get("updated_at") or "", a.get("id") or ""),
+                reverse=True,
+            )
+        elif sort == "updated_asc":
+            matched.sort(key=lambda a: (a.get("updated_at") or "", a.get("id") or ""))
+        elif sort == "name_asc":
+            matched.sort(key=lambda a: ((a.get("name") or "").lower(), a.get("id") or ""))
+        elif sort == "name_desc":
+            matched.sort(
+                key=lambda a: ((a.get("name") or "").lower(), a.get("id") or ""),
+                reverse=True,
+            )
+        else:
+            matched.sort(
+                key=lambda a: (a.get("created_at") or "", a.get("id") or ""),
+                reverse=True,
+            )
+        pin_ids = {agent_id for uid, agent_id in self._pins if uid == user_id}
+        matched.sort(key=lambda a: (0 if a.get("id") in pin_ids else 1,))
+        total = len(matched)
+        start = max(page - 1, 0) * page_size
         page_rows = matched[start : start + page_size]
         return [_copy(a) for a in page_rows], total
 
@@ -251,5 +275,23 @@ class MemoryAgentStore(AgentStore):
     async def list_favorite_ids(self, user_id: str) -> set[str]:
         return {agent_id for (uid, agent_id) in self._favorites if uid == user_id}
 
-    async def delete_favorites_for_agent(self, agent_id: str) -> None:
-        self._favorites = {(uid, aid) for (uid, aid) in self._favorites if aid != agent_id}
+    async def delete_favorites_for_agent(self, agent_id: str) -> None:
+        self._favorites = {(uid, aid) for (uid, aid) in self._favorites if aid != agent_id}
+
+    # --- Pins ("置顶") ---
+
+    async def add_pin(self, user_id: str, agent_id: str) -> None:
+        self._pins.add((user_id, agent_id))
+
+    async def remove_pin(self, user_id: str, agent_id: str) -> bool:
+        key = (user_id, agent_id)
+        if key not in self._pins:
+            return False
+        self._pins.remove(key)
+        return True
+
+    async def list_pin_ids(self, user_id: str) -> set[str]:
+        return {agent_id for uid, agent_id in self._pins if uid == user_id}
+
+    async def delete_pins_for_agent(self, agent_id: str) -> None:
+        self._pins = {(uid, aid) for (uid, aid) in self._pins if aid != agent_id}

offline-backend-20260512/backend/packages/harness/deerflow/persistence/agents/model.py

@@ -37,7 +37,7 @@ class AgentRow(Base):
     updated_at: Mapped[datetime] = mapped_column(BeijingDateTime(), nullable=False, default=lambda: datetime.now(UTC), onupdate=lambda: datetime.now(UTC))
 
 
-class AgentFavoriteRow(Base):
+class AgentFavoriteRow(Base):
     """A user's bookmark of a (typically public-square) agent.
 
     Lets a user collect agents from the 广场 (square) into their "我的" tab
@@ -51,10 +51,22 @@ class AgentFavoriteRow(Base):
     id: Mapped[str] = mapped_column(String(64), primary_key=True)
     user_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
     agent_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
-    created_at: Mapped[datetime] = mapped_column(BeijingDateTime(), nullable=False, default=lambda: datetime.now(UTC))
-
-
-class AgentSkillRow(Base):
+    created_at: Mapped[datetime] = mapped_column(BeijingDateTime(), nullable=False, default=lambda: datetime.now(UTC))
+
+
+class AgentPinRow(Base):
+    """A per-user pin that keeps an agent near the top of that user's lists."""
+
+    __tablename__ = "agent_pins"
+    __table_args__ = (UniqueConstraint("user_id", "agent_id", name="uq_agent_pins_user_agent"),)
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    user_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
+    agent_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
+    created_at: Mapped[datetime] = mapped_column(BeijingDateTime(), nullable=False, default=lambda: datetime.now(UTC))
+
+
+class AgentSkillRow(Base):
     """Denormalized cache of a custom agent's selected skills.
 
     ``config.yaml`` under ``.deer-flow/agents/{id}/`` stays the source of truth

offline-backend-20260512/backend/packages/harness/deerflow/persistence/agents/sql.py

@@ -6,18 +6,19 @@ from datetime import UTC, datetime
 from typing import Any
 from uuid import uuid4
 
-from sqlalchemy import and_, delete, func, or_, select
+from sqlalchemy import and_, case, delete, func, or_, select
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
 
 from deerflow.config.agent_name_desensitize import source_terms_for_needle
 from deerflow.persistence.agents.base import AgentStore
 from deerflow.persistence.agents.model import (
-    AgentExtrasRow,
-    AgentFavoriteRow,
-    AgentRow,
-    AgentSkillRow,
-)
+    AgentExtrasRow,
+    AgentFavoriteRow,
+    AgentPinRow,
+    AgentRow,
+    AgentSkillRow,
+)
 from deerflow.persistence.tags.model import TagAssignmentRow
 
 
@@ -277,17 +278,18 @@ class AgentRepository(AgentStore):
         )
         return AgentRow.id.in_(subq)
 
-    async def list_paginated(
-        self,
-        *,
-        user_id: str,
-        scope: str | None,
+    async def list_paginated(
+        self,
+        *,
+        user_id: str,
+        scope: str | None,
         search: str | None,
-        tag_ids: list[str] | None,
-        page: int,
-        page_size: int,
-        admin: bool = False,
-    ) -> tuple[list[dict[str, Any]], int]:
+        tag_ids: list[str] | None,
+        page: int,
+        page_size: int,
+        admin: bool = False,
+        sort: str = "time_desc",
+    ) -> tuple[list[dict[str, Any]], int]:
         filters = []
         scope_filter = self._scope_filter(user_id=user_id, scope=scope, admin=admin)
         if scope_filter is not None:
@@ -298,14 +300,28 @@ class AgentRepository(AgentStore):
             filters.append(self._tag_clause(tag_ids))
 
         count_stmt = select(func.count()).select_from(AgentRow)
-        page_stmt = (
-            select(AgentRow)
-            # ``id`` is a stable tiebreaker on top of ``created_at`` so OFFSET
-            # paging is deterministic when bulk-seeded built-ins share a timestamp.
-            .order_by(AgentRow.created_at.asc(), AgentRow.id.asc())
-            .limit(page_size)
-            .offset(max(page - 1, 0) * page_size)
-        )
+        pin_subq = select(AgentPinRow.agent_id).where(AgentPinRow.user_id == user_id)
+        pin_rank = case((AgentRow.id.in_(pin_subq), 0), else_=1)
+
+        if sort == "time_asc":
+            order_by = (AgentRow.created_at.asc(), AgentRow.id.asc())
+        elif sort == "updated_desc":
+            order_by = (AgentRow.updated_at.desc(), AgentRow.id.asc())
+        elif sort == "updated_asc":
+            order_by = (AgentRow.updated_at.asc(), AgentRow.id.asc())
+        elif sort == "name_asc":
+            order_by = (func.lower(AgentRow.name).asc(), AgentRow.id.asc())
+        elif sort == "name_desc":
+            order_by = (func.lower(AgentRow.name).desc(), AgentRow.id.asc())
+        else:
+            order_by = (AgentRow.created_at.desc(), AgentRow.id.asc())
+
+        page_stmt = (
+            select(AgentRow)
+            .order_by(pin_rank.asc(), *order_by)
+            .limit(page_size)
+            .offset(max(page - 1, 0) * page_size)
+        )
         if filters:
             where = and_(*filters)
             count_stmt = count_stmt.where(where)
@@ -425,7 +441,49 @@ class AgentRepository(AgentStore):
             )
             return {row[0] for row in result.all()}
 
-    async def delete_favorites_for_agent(self, agent_id: str) -> None:
-        async with self._sf() as session:
-            await session.execute(delete(AgentFavoriteRow).where(AgentFavoriteRow.agent_id == agent_id))
-            await session.commit()
+    async def delete_favorites_for_agent(self, agent_id: str) -> None:
+        async with self._sf() as session:
+            await session.execute(delete(AgentFavoriteRow).where(AgentFavoriteRow.agent_id == agent_id))
+            await session.commit()
+
+    # --- Pins ("置顶") ---
+
+    async def add_pin(self, user_id: str, agent_id: str) -> None:
+        async with self._sf() as session:
+            existing = (
+                await session.execute(
+                    select(AgentPinRow.id)
+                    .where(AgentPinRow.user_id == user_id, AgentPinRow.agent_id == agent_id)
+                    .limit(1)
+                )
+            ).scalar_one_or_none()
+            if existing is not None:
+                return
+            session.add(AgentPinRow(id=uuid4().hex, user_id=user_id, agent_id=agent_id))
+            try:
+                await session.commit()
+            except IntegrityError:
+                await session.rollback()
+
+    async def remove_pin(self, user_id: str, agent_id: str) -> bool:
+        async with self._sf() as session:
+            result = await session.execute(
+                delete(AgentPinRow).where(
+                    AgentPinRow.user_id == user_id,
+                    AgentPinRow.agent_id == agent_id,
+                )
+            )
+            await session.commit()
+            return (result.rowcount or 0) > 0
+
+    async def list_pin_ids(self, user_id: str) -> set[str]:
+        async with self._sf() as session:
+            result = await session.execute(
+                select(AgentPinRow.agent_id).where(AgentPinRow.user_id == user_id)
+            )
+            return {row[0] for row in result.all()}
+
+    async def delete_pins_for_agent(self, agent_id: str) -> None:
+        async with self._sf() as session:
+            await session.execute(delete(AgentPinRow).where(AgentPinRow.agent_id == agent_id))
+            await session.commit()

offline-backend-20260512/backend/packages/harness/deerflow/persistence/migrations/versions/20260604_01_agent_pins.py

@@ -0,0 +1,56 @@
+"""Per-user pinned agents.
+
+Revision ID: 20260604_01
+Revises: 20260603_03
+Create Date: 2026-06-04
+"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy import inspect
+
+
+revision = "20260604_01"
+down_revision = "20260603_03"
+branch_labels = None
+depends_on = None
+
+
+def _has_table(table_name: str) -> bool:
+    inspector = inspect(op.get_bind())
+    return table_name in inspector.get_table_names()
+
+
+def _has_index(table_name: str, index_name: str) -> bool:
+    if not _has_table(table_name):
+        return False
+    inspector = inspect(op.get_bind())
+    return any(idx["name"] == index_name for idx in inspector.get_indexes(table_name))
+
+
+def upgrade() -> None:
+    if not _has_table("agent_pins"):
+        op.create_table(
+            "agent_pins",
+            sa.Column("id", sa.String(64), nullable=False),
+            sa.Column("user_id", sa.String(64), nullable=False),
+            sa.Column("agent_id", sa.String(64), nullable=False),
+            sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+            sa.PrimaryKeyConstraint("id"),
+            sa.UniqueConstraint("user_id", "agent_id", name="uq_agent_pins_user_agent"),
+        )
+    if not _has_index("agent_pins", "ix_agent_pins_user_id"):
+        op.create_index("ix_agent_pins_user_id", "agent_pins", ["user_id"])
+    if not _has_index("agent_pins", "ix_agent_pins_agent_id"):
+        op.create_index("ix_agent_pins_agent_id", "agent_pins", ["agent_id"])
+
+
+def downgrade() -> None:
+    if _has_index("agent_pins", "ix_agent_pins_agent_id"):
+        op.drop_index("ix_agent_pins_agent_id", table_name="agent_pins")
+    if _has_index("agent_pins", "ix_agent_pins_user_id"):
+        op.drop_index("ix_agent_pins_user_id", table_name="agent_pins")
+    if _has_table("agent_pins"):
+        op.drop_table("agent_pins")

offline-backend-20260512/config.yaml

@@ -137,6 +137,28 @@ title:
 
     User: {user_msg}
     Assistant: {assistant_msg}
+# 上下文压缩(对话摘要):长对话接近上下文上限时,把较早的消息总结成一段摘要,
+# 只保留最近若干条原始消息,避免撑爆模型上下文窗口。
+# - trigger:触发条件,可配多个,任意一个先满足就压缩(OR 关系)。
+#     type=tokens   按 token 总数(最准,直接防溢出)
+#     type=messages 按消息条数(简单直观,作兜底保险)
+#     type=fraction 按模型上下文窗口的比例(如 0.8);自定义 base_url 模型可能探不到
+#                   准确窗口,故此处用写死的 token 阈值更稳妥。
+# - keep:压缩后保留多少最近的上下文(同样支持 tokens / messages / fraction)。
+# - trim_tokens_to_summarize:喂给摘要模型的消息最多裁到多少 token。
+# - model_name:生成摘要用的模型(留空则用主对话模型)。
+summarization:
+  enabled: true
+  # model_name: deepseek-chat
+  trigger:
+    - type: tokens
+      value: 60000
+    - type: messages
+      value: 80
+  keep:
+    type: messages
+    value: 20
+  trim_tokens_to_summarize: 4000
 skills:
   path: /app/skills
   security_scan: