feat: 支持智能体置顶配置

frontend-web/src/components/workspace/agents/agent-card.tsx

@@ -6,8 +6,9 @@ import {
   GlobeIcon,
   InfoIcon,
   LockIcon,
-  MessageSquareIcon,
-  ShieldIcon,
+  MessageSquareIcon,
+  PinIcon,
+  ShieldIcon,
   SparklesIcon,
   SquarePenIcon,
   StarIcon,
@@ -53,10 +54,11 @@ import {
   useAgent,
   useCreateAgent,
   useDeleteAgent,
-  useSetAgentFeatured,
-  useSetAgentPrivate,
-  useToggleAgentFavorite,
-  useUpdateAgent,
+  useSetAgentFeatured,
+  useSetAgentPrivate,
+  useToggleAgentFavorite,
+  useToggleAgentPin,
+  useUpdateAgent,
 } from "@/core/agents";
 import { getAgent } from "@/core/agents/api";
 import type { Agent } from "@/core/agents";
@@ -186,8 +188,9 @@ export function AgentCard({ agent }: AgentCardProps) {
   const updateAgent = useUpdateAgent();
   const createAgent = useCreateAgent();
   const setFeatured = useSetAgentFeatured();
-  const setPrivate = useSetAgentPrivate();
-  const toggleFavorite = useToggleAgentFavorite();
+  const setPrivate = useSetAgentPrivate();
+  const toggleFavorite = useToggleAgentFavorite();
+  const togglePin = useToggleAgentPin();
   const { skills, isLoading: isSkillsLoading } = useSkills();
   const [deleteOpen, setDeleteOpen] = useState(false);
   const [editOpen, setEditOpen] = useState(false);
@@ -225,7 +228,8 @@ export function AgentCard({ agent }: AgentCardProps) {
   // Favoriting collects a square agent into "我的"; pointless for one you
   // already own, so only offer it on built-in / others' agents.
   const canFavorite = !isOwned;
-  const isFavorite = !!agent.is_favorite;
+  const isFavorite = !!agent.is_favorite;
+  const isPinned = !!agent.is_pinned;
 
   useEffect(() => {
     if (!editOpen) {
@@ -379,7 +383,7 @@ export function AgentCard({ agent }: AgentCardProps) {
     }
   }
 
-  async function handleToggleFavorite() {
+  async function handleToggleFavorite() {
     const next = !isFavorite;
     try {
       await toggleFavorite.mutateAsync({ id: agent.id, favorite: next });
@@ -387,7 +391,17 @@ export function AgentCard({ agent }: AgentCardProps) {
     } catch (err) {
       toast.error(err instanceof Error ? err.message : String(err));
     }
-  }
+  }
+
+  async function handleTogglePin() {
+    const next = !isPinned;
+    try {
+      await togglePin.mutateAsync({ id: agent.id, pinned: next });
+      toast.success(next ? "已置顶" : "已取消置顶");
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : String(err));
+    }
+  }
 
   async function handleToggleFeatured() {
     // One-click on/off — ordering is handled by the dedicated 管理 Agent 列表
@@ -552,8 +566,8 @@ export function AgentCard({ agent }: AgentCardProps) {
         <CardFooter className="mt-auto flex flex-col items-stretch gap-2 pt-3">
           {(canEdit || canDelete || isOwned || isAdmin || canFavorite) && (
             <div className="flex flex-wrap items-center justify-end gap-1">
-              {canFavorite && (
-                <Button
+              {canFavorite && (
+                <Button
                   size="icon"
                   variant="ghost"
                   className={cn(
@@ -567,9 +581,23 @@ export function AgentCard({ agent }: AgentCardProps) {
                   <StarIcon
                     className={cn("h-3.5 w-3.5", isFavorite && "fill-current")}
                   />
-                </Button>
-              )}
-              {isAdmin && (
+                </Button>
+              )}
+              <Button
+                size="icon"
+                variant="ghost"
+                className={cn(
+                  "h-8 w-8 shrink-0",
+                  isPinned && "text-emerald-600 hover:text-emerald-700",
+                  !canFavorite && "mr-auto",
+                )}
+                onClick={() => void handleTogglePin()}
+                disabled={togglePin.isPending}
+                title={isPinned ? "取消置顶" : "置顶"}
+              >
+                <PinIcon className={cn("h-3.5 w-3.5", isPinned && "fill-current")} />
+              </Button>
+              {isAdmin && (
                 <Button
                   size="icon"
                   variant="ghost"

frontend-web/src/components/workspace/agents/agent-gallery.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { BotIcon, LockIcon, PlusIcon, ShieldIcon } from "lucide-react";
+import { ArrowDownUpIcon, BotIcon, LockIcon, PlusIcon, ShieldIcon } from "lucide-react";
 import { useRouter } from "next/navigation";
 import { useEffect, useState } from "react";
 import { toast } from "sonner";
@@ -8,10 +8,11 @@ import { toast } from "sonner";
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import { Pagination } from "@/components/ui/pagination";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
 import { TagSearchBar } from "@/components/workspace/tags/tag-search-bar";
 import { useAgentsPaginated, usePrivateAgentsPaginated } from "@/core/agents";
-import type { Agent } from "@/core/agents";
+import type { Agent, AgentSort } from "@/core/agents";
 import { useI18n } from "@/core/i18n/hooks";
 import { usePrivateSquareStatus } from "@/core/system-settings/hooks";
 
@@ -32,6 +33,7 @@ export function AgentGallery() {
   );
   const [search, setSearch] = useState("");
   const [tagIds, setTagIds] = useState<string[]>([]);
+  const [sort, setSort] = useState<AgentSort>("time_desc");
   // Per-tab 1-based page index, preserved while switching tabs.
   const [pages, setPages] = useState<{ all: number; mine: number; private: number }>(
     { all: 1, mine: 1, private: 1 },
@@ -44,7 +46,7 @@ export function AgentGallery() {
   const tagKey = tagIds.join(",");
   useEffect(() => {
     setPages({ all: 1, mine: 1, private: 1 });
-  }, [search, tagKey]);
+  }, [search, tagKey, sort]);
 
   const { data: privateStatus } = usePrivateSquareStatus();
   const privateFeatureAvailable = !!privateStatus?.enabled;
@@ -69,6 +71,7 @@ export function AgentGallery() {
     scope: mainScope,
     search,
     tagIds,
+    sort,
     page: mainPage,
     pageSize: PAGE_SIZE,
     enabled: activeTab !== "private",
@@ -82,6 +85,7 @@ export function AgentGallery() {
   } = usePrivateAgentsPaginated(privatePassword, {
     search,
     tagIds,
+    sort,
     page: pages.private,
     pageSize: PAGE_SIZE,
     enabled: activeTab === "private",
@@ -98,7 +102,6 @@ export function AgentGallery() {
   }, [privateError, privatePassword]);
 
   const activeTotal = activeTab === "private" ? privateTotal : mainTotal;
-
   const setTabPage = (tab: "all" | "mine" | "private", page: number) =>
     setPages((prev) => ({ ...prev, [tab]: page }));
 
@@ -240,6 +243,15 @@ export function AgentGallery() {
               onKeyDown={(e) => {
                 if (e.key === "Enter") handleSubmitPassword();
               }}
+              // This is a one-off access code, not a login credential. Tell
+              // browsers / password managers not to save or autofill it (which
+              // would also stop them from spilling a saved account into the
+              // name search box on this page).
+              name="private-square-access-code"
+              autoComplete="off"
+              data-1p-ignore
+              data-lpignore="true"
+              data-form-type="other"
             />
             <Button onClick={handleSubmitPassword}>进入私密广场</Button>
           </div>
@@ -314,6 +326,25 @@ export function AgentGallery() {
             onSearchChange={setSearch}
             tagIds={tagIds}
             onTagIdsChange={setTagIds}
+            actions={
+              <Select value={sort} onValueChange={(v) => setSort(v as AgentSort)}>
+                <SelectTrigger
+                  className="h-9 w-full gap-2 px-3 text-xs sm:w-[148px]"
+                  title="排序"
+                >
+                  <ArrowDownUpIcon className="text-muted-foreground size-3.5" />
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent position="popper" side="bottom" sideOffset={4}>
+                  <SelectItem value="time_desc">最新创建</SelectItem>
+                  <SelectItem value="time_asc">最早创建</SelectItem>
+                  <SelectItem value="updated_desc">最近更新</SelectItem>
+                  <SelectItem value="updated_asc">最早更新</SelectItem>
+                  <SelectItem value="name_asc">名称 A-Z</SelectItem>
+                  <SelectItem value="name_desc">名称 Z-A</SelectItem>
+                </SelectContent>
+              </Select>
+            }
           />
         </div>
 

frontend-web/src/components/workspace/custom-prompt-menu.tsx

@@ -7,7 +7,7 @@ import {
   Settings2Icon,
   Trash2Icon,
 } from "lucide-react";
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { toast } from "sonner";
 
 import { Button } from "@/components/ui/button";
@@ -193,6 +193,19 @@ function ManagePromptsDialog({
   const agentNameById = (id?: string | null) =>
     id ? agents.find((a) => a.id === id)?.name ?? null : null;
 
+  // Only offer the agents the user has favorited (收藏到「我的」) for
+  // association — the full catalog is huge, mostly irrelevant, and overflowed
+  // the dropdown. The agent a prompt is *already* bound to is kept in the list
+  // even if it is no longer a favorite, so editing never silently drops it.
+  const selectableAgents = useMemo(() => {
+    const favorites = agents.filter((a) => a.is_favorite);
+    if (agentId !== NO_AGENT && !favorites.some((a) => a.id === agentId)) {
+      const bound = agents.find((a) => a.id === agentId);
+      if (bound) return [bound, ...favorites];
+    }
+    return favorites;
+  }, [agents, agentId]);
+
   const resetForm = () => {
     setEditingId(null);
     setTitle("");
@@ -299,23 +312,27 @@ function ManagePromptsDialog({
           <div className="flex flex-col gap-1">
             <p className="text-muted-foreground text-xs">关联智能体（可选）</p>
             <Select value={agentId} onValueChange={setAgentId}>
-              <SelectTrigger className="w-full min-w-0 max-w-full overflow-hidden [&>span]:min-w-0 [&>span]:flex-1 [&>span]:truncate">
+              <SelectTrigger className="w-full min-w-0 max-w-full overflow-hidden [&>span]:min-w-0 [&>span]:flex-1 [&>span]:truncate [&>span]:text-left">
                 <SelectValue placeholder="不关联（所有对话可见）" />
               </SelectTrigger>
               <SelectContent
                 position="popper"
-                className="w-[var(--radix-select-trigger-width)] max-w-[var(--radix-select-trigger-width)]"
+                className="max-h-[40vh] w-[var(--radix-select-trigger-width)] max-w-[var(--radix-select-trigger-width)]"
               >
                 <SelectItem value={NO_AGENT}>不关联（所有对话可见）</SelectItem>
-                {agents.map((agent) => (
-                  <SelectItem key={agent.id} value={agent.id}>
-                    <span className="block truncate">{desensitize(agent.name)}</span>
+                {selectableAgents.map((agent) => (
+                  <SelectItem key={agent.id} value={agent.id} className="pr-8">
+                    <span className="block max-w-full truncate">
+                      {desensitize(agent.name)}
+                    </span>
                   </SelectItem>
                 ))}
               </SelectContent>
             </Select>
             <p className="text-muted-foreground text-xs">
-              关联后，仅在选中该智能体的对话里显示此提示词。
+              {selectableAgents.length === 0
+                ? "仅可关联你收藏到「我的」的常用智能体；当前还没有收藏任何智能体。"
+                : "关联后，仅在选中该智能体的对话里显示此提示词。这里只列出你收藏的常用智能体。"}
             </p>
           </div>
           <div className="flex justify-end gap-2">

frontend-web/src/components/workspace/settings/skill-settings-page.tsx

@@ -1,9 +1,10 @@
 "use client";
 
 import {
-  AlertCircle,
-  ArchiveIcon,
-  CheckCircle2,
+  AlertCircle,
+  ArchiveIcon,
+  ArrowDownUpIcon,
+  CheckCircle2,
   ChevronLeftIcon,
   ChevronRightIcon,
   ClockIcon,
@@ -51,8 +52,9 @@ import {
   ItemContent,
   ItemDescription,
 } from "@/components/ui/item";
-import { Input } from "@/components/ui/input";
-import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs";
+import { Input } from "@/components/ui/input";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
+import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs";
 import { SkillDetailDialog } from "@/components/workspace/skills/skill-detail-dialog";
 import { TagChipList } from "@/components/workspace/tags/tag-chip";
 import { TagPickerDialog } from "@/components/workspace/tags/tag-picker-dialog";
@@ -91,7 +93,16 @@ export function SkillSettingsPage({ onClose }: { onClose?: () => void } = {}) {
   );
 }
 
-const PAGE_SIZE = 10;
+const PAGE_SIZE = 10;
+type SkillSort =
+  | "time_desc"
+  | "time_asc"
+  | "activity_desc"
+  | "activity_asc"
+  | "usage_desc"
+  | "usage_asc"
+  | "name_asc"
+  | "name_desc";
 
 /** 重新扫描成功 toast：仅暗色模式使用，浅色走 Sonner 默认样式 */
 const rescanSuccessToastDarkOptions = {
@@ -134,12 +145,13 @@ function SkillSettingsList({ onClose }: { onClose?: () => void }) {
   const [installOpen, setInstallOpen] = useState(false);
   const [staleSheetOpen, setStaleSheetOpen] = useState(false);
   const [archiveSheetOpen, setArchiveSheetOpen] = useState(false);
-  const [search, setSearch] = useState("");
-  const [tagIds, setTagIds] = useState<string[]>([]);
-  const [page, setPage] = useState(1);
-  const reconcileMutation = useReconcileCustomSkills();
-  // Name + tag filtering is resolved server-side via the /api/skills query.
-  const { skills, isLoading, error } = useSkills({ search, tagIds });
+  const [search, setSearch] = useState("");
+  const [tagIds, setTagIds] = useState<string[]>([]);
+  const [sort, setSort] = useState<SkillSort>("time_desc");
+  const [page, setPage] = useState(1);
+  const reconcileMutation = useReconcileCustomSkills();
+  // Name + tag filtering is resolved server-side via the /api/skills query.
+  const { skills, isLoading, error } = useSkills({ search, tagIds, sort });
 
   const storedAuth = useMemo(() => getStoredAuth(), []);
   const currentUserId = storedAuth?.user_id ?? null;
@@ -191,9 +203,12 @@ function SkillSettingsList({ onClose }: { onClose?: () => void }) {
   const totalPages = Math.max(1, Math.ceil(filteredSkills.length / PAGE_SIZE));
   // Filter / search / tag changes may shrink the result set — pull the page
   // back into range without forcing a reset on every keystroke.
-  useEffect(() => {
-    if (page > totalPages) setPage(totalPages);
-  }, [page, totalPages]);
+  useEffect(() => {
+    if (page > totalPages) setPage(totalPages);
+  }, [page, totalPages]);
+  useEffect(() => {
+    setPage(1);
+  }, [search, tagIds, sort]);
   const pagedSkills = useMemo(
     () => filteredSkills.slice((page - 1) * PAGE_SIZE, page * PAGE_SIZE),
     [filteredSkills, page],
@@ -309,12 +324,33 @@ function SkillSettingsList({ onClose }: { onClose?: () => void }) {
           </Button>
         </div>
       </header>
-      <TagSearchBar
-        targetType="skill"
-        onSearchChange={setSearch}
-        tagIds={tagIds}
-        onTagIdsChange={setTagIds}
-      />
+      <TagSearchBar
+        targetType="skill"
+        onSearchChange={setSearch}
+        tagIds={tagIds}
+        onTagIdsChange={setTagIds}
+        actions={
+          <Select value={sort} onValueChange={(v) => setSort(v as SkillSort)}>
+            <SelectTrigger
+              className="h-9 w-full gap-2 px-3 text-xs sm:w-[148px]"
+              title="排序"
+            >
+              <ArrowDownUpIcon className="text-muted-foreground size-3.5" />
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent position="popper" side="bottom" sideOffset={4}>
+              <SelectItem value="time_desc">最新创建</SelectItem>
+              <SelectItem value="time_asc">最早创建</SelectItem>
+              <SelectItem value="activity_desc">最近使用</SelectItem>
+              <SelectItem value="activity_asc">最早使用</SelectItem>
+              <SelectItem value="usage_desc">使用最多</SelectItem>
+              <SelectItem value="usage_asc">使用最少</SelectItem>
+              <SelectItem value="name_asc">名称 A-Z</SelectItem>
+              <SelectItem value="name_desc">名称 Z-A</SelectItem>
+            </SelectContent>
+          </Select>
+        }
+      />
       {isLoading && (
         <div className="text-muted-foreground text-sm">{t.common.loading}</div>
       )}

frontend-web/src/components/workspace/tags/tag-search-bar.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import { CheckIcon, ChevronDownIcon, ChevronUpIcon, SearchIcon } from "lucide-react";
-import { useEffect, useRef, useState } from "react";
+import { useEffect, useRef, useState, type ReactNode } from "react";
 
 import { Input } from "@/components/ui/input";
 import { useI18n } from "@/core/i18n/hooks";
@@ -31,12 +31,14 @@ export function TagSearchBar({
   tagIds,
   onTagIdsChange,
   className,
+  actions,
 }: {
   targetType: TagType;
   onSearchChange: (value: string) => void;
   tagIds: string[];
   onTagIdsChange: (value: string[]) => void;
   className?: string;
+  actions?: ReactNode;
 }) {
   const { t } = useI18n();
   const { data: tags } = useTags(targetType);
@@ -67,14 +69,31 @@ export function TagSearchBar({
 
   return (
     <div className={cn("flex flex-col gap-2.5", className)}>
-      <div className="relative">
-        <SearchIcon className="text-muted-foreground dark:text-[#60a5fa]/90 absolute left-2.5 top-1/2 size-4 -translate-y-1/2" />
-        <Input
-          value={input}
-          onChange={(e) => setInput(e.target.value)}
-          placeholder={t.adminTags.searchPlaceholder}
-          className="pl-8"
-        />
+      <div className="flex flex-col gap-2 sm:flex-row sm:items-center">
+        <div className="relative min-w-0 flex-1">
+          <SearchIcon className="text-muted-foreground dark:text-[#60a5fa]/90 absolute left-2.5 top-1/2 size-4 -translate-y-1/2" />
+          <Input
+            value={input}
+            onChange={(e) => setInput(e.target.value)}
+            placeholder={t.adminTags.searchPlaceholder}
+            className="pl-8"
+            name="tag-search"
+            // A `type="password"` field elsewhere on the page (e.g. the private
+            // square access gate) makes browsers / password managers pick the
+            // nearest text input as the "username" and autofill the account into
+            // it. Mark this search box so it is never treated as a credential
+            // field.
+            autoComplete="off"
+            data-1p-ignore
+            data-lpignore="true"
+            data-form-type="other"
+          />
+        </div>
+        {actions && (
+          <div className="flex w-full shrink-0 justify-end sm:w-auto">
+            {actions}
+          </div>
+        )}
       </div>
 
       {allTags.length > 0 && (

frontend-web/src/core/agents/api.ts

@@ -2,12 +2,13 @@ import { getBackendBaseURL } from "@/core/config";
 import { apiFetch } from "@/core/api";
 
 import type {
-  Agent,
-  AgentSelectorResponse,
-  CreateAgentRequest,
-  PaginatedAgents,
-  UpdateAgentRequest,
-} from "./types";
+  Agent,
+  AgentSelectorResponse,
+  AgentSort,
+  CreateAgentRequest,
+  PaginatedAgents,
+  UpdateAgentRequest,
+} from "./types";
 
 const BACKEND_UNAVAILABLE_STATUSES = new Set([502, 503, 504]);
 
@@ -27,19 +28,21 @@ export interface ListAgentsParams {
   /** Pagination scope. Omit for the legacy combined-visibility list. */
   scope?: "mine" | "square";
   /** 1-based page index. Providing this (or scope) enables server-side pagination. */
-  page?: number;
-  pageSize?: number;
-}
+  page?: number;
+  pageSize?: number;
+  sort?: AgentSort;
+}
 
 function buildAgentsQuery(params: ListAgentsParams): string {
   const qs = new URLSearchParams();
   if (params.search) qs.set("search", params.search);
   for (const id of params.tagIds ?? []) qs.append("tag_ids", id);
   if (params.scope) qs.set("scope", params.scope);
-  if (params.page != null) qs.set("page", String(params.page));
-  if (params.pageSize != null) qs.set("page_size", String(params.pageSize));
-  return qs.toString();
-}
+  if (params.page != null) qs.set("page", String(params.page));
+  if (params.pageSize != null) qs.set("page_size", String(params.pageSize));
+  if (params.sort) qs.set("sort", params.sort);
+  return qs.toString();
+}
 
 export async function listAgents(params: ListAgentsParams = {}): Promise<Agent[]> {
   const query = buildAgentsQuery(params);
@@ -126,13 +129,13 @@ export async function deleteAgent(id: string): Promise<void> {
   if (!res.ok) throw new Error(`Failed to delete agent: ${res.statusText}`);
 }
 
-export async function getAgentSelector(): Promise<AgentSelectorResponse> {
+export async function getAgentSelector(): Promise<AgentSelectorResponse> {
   const res = await apiFetch(`${getBackendBaseURL()}/api/agents/selector`);
   if (!res.ok) throw new Error(`Failed to load agent selector: ${res.statusText}`);
   return res.json() as Promise<AgentSelectorResponse>;
-}
-
-export async function favoriteAgent(id: string): Promise<void> {
+}
+
+export async function favoriteAgent(id: string): Promise<void> {
   const res = await apiFetch(`${getBackendBaseURL()}/api/agents/${id}/favorite`, {
     method: "POST",
   });
@@ -142,15 +145,35 @@ export async function favoriteAgent(id: string): Promise<void> {
   }
 }
 
-export async function unfavoriteAgent(id: string): Promise<void> {
+export async function unfavoriteAgent(id: string): Promise<void> {
   const res = await apiFetch(`${getBackendBaseURL()}/api/agents/${id}/favorite`, {
     method: "DELETE",
   });
   if (!res.ok) {
     const err = (await res.json().catch(() => ({}))) as { detail?: string };
     throw new Error(err.detail ?? `Failed to unfavorite agent: ${res.statusText}`);
-  }
-}
+  }
+}
+
+export async function pinAgent(id: string): Promise<void> {
+  const res = await apiFetch(`${getBackendBaseURL()}/api/agents/${id}/pin`, {
+    method: "POST",
+  });
+  if (!res.ok) {
+    const err = (await res.json().catch(() => ({}))) as { detail?: string };
+    throw new Error(err.detail ?? `Failed to pin agent: ${res.statusText}`);
+  }
+}
+
+export async function unpinAgent(id: string): Promise<void> {
+  const res = await apiFetch(`${getBackendBaseURL()}/api/agents/${id}/pin`, {
+    method: "DELETE",
+  });
+  if (!res.ok) {
+    const err = (await res.json().catch(() => ({}))) as { detail?: string };
+    throw new Error(err.detail ?? `Failed to unpin agent: ${res.statusText}`);
+  }
+}
 
 export async function reorderFeaturedAgents(agentIds: string[]): Promise<void> {
   const res = await apiFetch(
@@ -188,13 +211,14 @@ export async function listPrivateAgents(password: string): Promise<Agent[]> {
   return data.agents;
 }
 
-export interface ListPrivateAgentsParams {
-  password: string;
-  search?: string;
-  tagIds?: string[];
-  page?: number;
-  pageSize?: number;
-}
+export interface ListPrivateAgentsParams {
+  password: string;
+  search?: string;
+  tagIds?: string[];
+  page?: number;
+  pageSize?: number;
+  sort?: AgentSort;
+}
 
 /** Paginated private-square listing (password-gated). */
 export async function listPrivateAgentsPaginated(
@@ -208,10 +232,11 @@ export async function listPrivateAgentsPaginated(
       body: JSON.stringify({
         password: params.password,
         search: params.search || undefined,
-        tag_ids: params.tagIds && params.tagIds.length ? params.tagIds : undefined,
-        page: params.page,
-        page_size: params.pageSize,
-      }),
+        tag_ids: params.tagIds && params.tagIds.length ? params.tagIds : undefined,
+        page: params.page,
+        page_size: params.pageSize,
+        sort: params.sort,
+      }),
     },
   );
   if (!res.ok) {

frontend-web/src/core/agents/hooks.ts

@@ -3,31 +3,34 @@ import {
   useMutation,
   useQuery,
   useQueryClient,
-} from "@tanstack/react-query";
-
-import {
+} from "@tanstack/react-query";
+
+import {
   adminSyncAgentSkills,
   createAgent,
   deleteAgent,
   favoriteAgent,
   getAgent,
   getAgentSelector,
-  listAgents,
-  listAgentsPaginated,
-  listAllAgentsAdmin,
-  listPrivateAgents,
-  listPrivateAgentsPaginated,
-  reorderFeaturedAgents,
-  setAgentFeatured,
-  setAgentPrivate,
-  unfavoriteAgent,
-  updateAgent,
-} from "./api";
-import type {
-  Agent,
-  CreateAgentRequest,
-  PaginatedAgents,
-  UpdateAgentRequest,
+  listAgents,
+  listAgentsPaginated,
+  listAllAgentsAdmin,
+  listPrivateAgents,
+  listPrivateAgentsPaginated,
+  pinAgent,
+  reorderFeaturedAgents,
+  setAgentFeatured,
+  setAgentPrivate,
+  unfavoriteAgent,
+  unpinAgent,
+  updateAgent,
+} from "./api";
+import type {
+  Agent,
+  AgentSort,
+  CreateAgentRequest,
+  PaginatedAgents,
+  UpdateAgentRequest,
 } from "./types";
 
 /** A cached agent listing is either a plain ``Agent[]`` (legacy ``useAgents``)
@@ -76,28 +79,31 @@ export function useAgents(params: { search?: string; tagIds?: string[] } = {}) {
 /** Server-side paginated agent listing for one gallery tab (scope). Returns
  * the page of agents plus the total count for the "共 N 个" header. */
 export function useAgentsPaginated(params: {
-  scope: "mine" | "square";
-  search?: string;
-  tagIds?: string[];
-  page: number;
-  pageSize: number;
-  enabled?: boolean;
-}) {
-  const { scope, page, pageSize, enabled = true } = params;
-  const search = params.search ?? "";
-  const tagIds = params.tagIds ?? [];
+  scope: "mine" | "square";
+  search?: string;
+  tagIds?: string[];
+  sort?: AgentSort;
+  page: number;
+  pageSize: number;
+  enabled?: boolean;
+}) {
+  const { scope, page, pageSize, enabled = true } = params;
+  const search = params.search ?? "";
+  const tagIds = params.tagIds ?? [];
+  const sort = params.sort ?? "time_desc";
   const { data, isLoading, error } = useQuery({
     queryKey: [
       "agents",
       "paginated",
-      scope,
-      search,
-      [...tagIds].sort(),
-      page,
-      pageSize,
-    ],
-    queryFn: () =>
-      listAgentsPaginated({ scope, search, tagIds, page, pageSize }),
+      scope,
+      search,
+      [...tagIds].sort(),
+      sort,
+      page,
+      pageSize,
+    ],
+    queryFn: () =>
+      listAgentsPaginated({ scope, search, tagIds, sort, page, pageSize }),
     enabled,
     placeholderData: keepPreviousData,
   });
@@ -174,7 +180,7 @@ export function useDeleteAgent() {
 /** Toggle a user's favorite (收藏) on an agent, with an optimistic flip of
  * ``is_favorite`` across every cached agent listing + detail so the star
  * reacts instantly before the round-trip completes. */
-export function useToggleAgentFavorite() {
+export function useToggleAgentFavorite() {
   const queryClient = useQueryClient();
   return useMutation({
     mutationFn: ({ id, favorite }: { id: string; favorite: boolean }) =>
@@ -190,10 +196,30 @@ export function useToggleAgentFavorite() {
     onSettled: () => {
       void queryClient.invalidateQueries({ queryKey: ["agents"] });
     },
-  });
-}
-
-export function useAgentSelector() {
+  });
+}
+
+export function useToggleAgentPin() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: ({ id, pinned }: { id: string; pinned: boolean }) =>
+      pinned ? pinAgent(id) : unpinAgent(id),
+    onMutate: ({ id, pinned }) => {
+      mapCachedAgents(queryClient, (a) =>
+        a.id === id ? { ...a, is_pinned: pinned } : a,
+      );
+      queryClient.setQueryData<Agent | undefined>(["agents", id], (old) =>
+        old ? { ...old, is_pinned: pinned } : old,
+      );
+    },
+    onSuccess: async () => {
+      await queryClient.invalidateQueries({ queryKey: ["agents"] });
+      await queryClient.refetchQueries({ queryKey: ["agents"], type: "active" });
+    },
+  });
+}
+
+export function useAgentSelector() {
   const { data, isLoading, error } = useQuery({
     queryKey: ["agents", "selector"],
     queryFn: () => getAgentSelector(),
@@ -204,9 +230,9 @@ export function useAgentSelector() {
     isLoading,
     error,
   };
-}
-
-function invalidateAgentQueries(queryClient: ReturnType<typeof useQueryClient>) {
+}
+
+function invalidateAgentQueries(queryClient: ReturnType<typeof useQueryClient>) {
   void queryClient.invalidateQueries({ queryKey: ["agents"] });
 }
 
@@ -251,35 +277,39 @@ export function usePrivateAgents(password: string | null) {
  * password-gated private square plus the total count. */
 export function usePrivateAgentsPaginated(
   password: string | null,
-  params: {
-    search?: string;
-    tagIds?: string[];
-    page: number;
-    pageSize: number;
-    enabled?: boolean;
-  },
-) {
-  const { page, pageSize, enabled = true } = params;
-  const search = params.search ?? "";
-  const tagIds = params.tagIds ?? [];
+  params: {
+    search?: string;
+    tagIds?: string[];
+    sort?: AgentSort;
+    page: number;
+    pageSize: number;
+    enabled?: boolean;
+  },
+) {
+  const { page, pageSize, enabled = true } = params;
+  const search = params.search ?? "";
+  const tagIds = params.tagIds ?? [];
+  const sort = params.sort ?? "time_desc";
   const { data, isLoading, error, refetch } = useQuery({
     queryKey: [
       "agents",
       "private-square",
       password ?? "",
-      "paginated",
-      search,
-      [...tagIds].sort(),
-      page,
-      pageSize,
+      "paginated",
+      search,
+      [...tagIds].sort(),
+      sort,
+      page,
+      pageSize,
     ],
     queryFn: () =>
       listPrivateAgentsPaginated({
-        password: password!,
-        search,
-        tagIds,
-        page,
-        pageSize,
+        password: password!,
+        search,
+        tagIds,
+        sort,
+        page,
+        pageSize,
       }),
     enabled: !!password && enabled,
     staleTime: 30_000,

frontend-web/src/core/agents/types.ts

@@ -1,6 +1,6 @@
 import type { Tag } from "@/core/tags";
 
-export interface Agent {
+export interface Agent {
   id: string;
   name: string;
   description: string;
@@ -17,12 +17,15 @@ export interface Agent {
   tags?: Tag[];
   featured_order?: number | null;
   /** Whether the current user has favorited (收藏) this agent. */
-  is_favorite?: boolean;
-}
-
-export interface AgentSelectorResponse {
-  agents: Agent[];
-}
+  is_favorite?: boolean;
+  is_pinned?: boolean;
+}
+
+export type AgentSort = "time_desc" | "time_asc" | "updated_desc" | "updated_asc" | "name_asc" | "name_desc";
+
+export interface AgentSelectorResponse {
+  agents: Agent[];
+}
 
 /** Pagination envelope returned by the server-side paginated agent listings. */
 export interface PaginatedAgents {

frontend-web/src/core/skills/api.ts

@@ -3,15 +3,17 @@ import { apiFetch } from "@/core/api";
 
 import type { Skill, SkillDisplayConfig, SkillState } from "./type";
 
-export interface ListSkillsParams {
-  search?: string;
-  tagIds?: string[];
-}
+export interface ListSkillsParams {
+  search?: string;
+  tagIds?: string[];
+  sort?: "time_desc" | "time_asc" | "activity_desc" | "activity_asc" | "usage_desc" | "usage_asc" | "name_asc" | "name_desc";
+}
 
 export async function loadSkills(params: ListSkillsParams = {}) {
   const qs = new URLSearchParams();
-  if (params.search) qs.set("search", params.search);
-  for (const id of params.tagIds ?? []) qs.append("tag_ids", id);
+  if (params.search) qs.set("search", params.search);
+  for (const id of params.tagIds ?? []) qs.append("tag_ids", id);
+  if (params.sort) qs.set("sort", params.sort);
   const query = qs.toString();
   const skills = await apiFetch(
     `${getBackendBaseURL()}/api/skills${query ? `?${query}` : ""}`,

frontend-web/src/core/skills/hooks.ts

@@ -1,4 +1,4 @@
-import {
+import {
   keepPreviousData,
   useMutation,
   useQuery,
@@ -22,7 +22,8 @@ import {
   setSkillPublished,
   setSkillState,
   validateSkillUpload,
-} from "./api";
+} from "./api";
+import type { ListSkillsParams } from "./api";
 import type { Skill, SkillState } from "./type";
 
 import { loadAllSkillsAdmin, loadSkills } from ".";
@@ -33,12 +34,13 @@ import { loadAllSkillsAdmin, loadSkills } from ".";
 // forever (observed as a "Maximum update depth exceeded" loop on NewAgentPage).
 const EMPTY_SKILLS: Skill[] = [];
 
-export function useSkills(params: { search?: string; tagIds?: string[] } = {}) {
-  const search = params.search ?? "";
-  const tagIds = params.tagIds ?? [];
-  const { data, isLoading, error } = useQuery({
-    queryKey: ["skills", search, [...tagIds].sort()],
-    queryFn: () => loadSkills({ search, tagIds }),
+export function useSkills(params: ListSkillsParams = {}) {
+  const search = params.search ?? "";
+  const tagIds = params.tagIds ?? [];
+  const sort = params.sort ?? "time_desc";
+  const { data, isLoading, error } = useQuery({
+    queryKey: ["skills", search, [...tagIds].sort(), sort],
+    queryFn: () => loadSkills({ search, tagIds, sort }),
     placeholderData: keepPreviousData,
   });
   return { skills: data ?? EMPTY_SKILLS, isLoading, error };

frontend-web/src/core/skills/type.ts

@@ -63,6 +63,7 @@ export interface Skill {
   // Provenance — distinguishes skills created by an agent during a chat
   // (``agent``) from skills the user uploaded / authored manually (``upload``).
   source?: SkillSource;
+  created_at?: string | null;
   last_activity_at?: string | null;
   use_count?: number;
   view_count?: number;

frontend-web/src/core/user-preferences/index.ts

@@ -52,6 +52,25 @@ export function useUpdateUserPreferences() {
   const queryClient = useQueryClient();
   return useMutation({
     mutationFn: updateUserPreferences,
+    // Optimistically flip the cached preference so the switch — and every
+    // surface that reacts to it (e.g. the chat input's admin prompt-prefix
+    // toggle) — updates instantly instead of waiting for the round-trip,
+    // which made the toggle look like it "didn't take effect / didn't refresh".
+    onMutate: async (input) => {
+      await queryClient.cancelQueries({ queryKey: QUERY_KEY });
+      const previous = queryClient.getQueryData<UserPreferences>(QUERY_KEY);
+      queryClient.setQueryData<UserPreferences>(QUERY_KEY, (old) => ({
+        ...(old ?? DEFAULT_PREFS),
+        ...input,
+      }));
+      return { previous };
+    },
+    onError: (_err, _input, context) => {
+      // Roll back to the pre-toggle value if the server rejected the change.
+      if (context?.previous) {
+        queryClient.setQueryData(QUERY_KEY, context.previous);
+      }
+    },
     onSuccess: (data) => {
       queryClient.setQueryData(QUERY_KEY, data);
     },