chore: 清理项目中冗余/过时的代码注释

- 删除 thread.tsx 中重复说明属性名/函数名的"是什么"注释（标识符已自解释）
- 移除 DocsAssistant.tsx 的占位注释（"其他需要的属性..."）和重复 state 说明，
  保留并精炼真正解释"为什么"需要 loader/pending 缓存的注释
- 删除 HotDocsTab.tsx、LinkCard.tsx 中纯标签 JSX 区段（"加载状态/列表/标题"等）
- 删除 ZoteroFeed.tsx 中误导性的 "Debug helpers (removed in production)" 残留标记
- 删除 assistant-modal.tsx 中 issue #285 任务引用，保留受控 state 的 WHY 说明
- 删除 generate-leaderboard.mjs 中已不适用的"历史：早期直连 Postgres"段落

保留所有解释 WHY 的踩坑记录、不变式、降级策略等有价值注释。

Author: claude

app/[locale]/feed/components/LinkCard.tsx

@@ -33,15 +33,13 @@ export function LinkCard({ link, categoryLabel, isLoggedIn }: LinkCardProps) {
 
   return (
     <li className="group border border-[var(--foreground)] hover:border-[#CC0000] transition-colors duration-150 flex flex-col">
-      {/* 整卡可点击区域，跳到原文 */}
       <a
         href={link.url}
         target="_blank"
         rel="noopener noreferrer"
         className="flex flex-col flex-1"
         aria-label={link.ogTitle ?? link.url}
       >
-        {/* OG 封面 / 占位块 */}
         {safeOgCover && !link.ogFetchFailed ? (
           // next/image 全站 unoptimized:true，用 img 即可（与 events 页一致）。
           // referrerPolicy="no-referrer"：微信 mmbiz.qpic.cn 防盗链会检查 Referer，
@@ -55,7 +53,6 @@ export function LinkCard({ link, categoryLabel, isLoggedIn }: LinkCardProps) {
             className="w-full aspect-[16/9] object-cover border-b border-[var(--foreground)]"
           />
         ) : (
-          // 无封面：显示 host 首字母占位
           <div className="w-full aspect-[16/9] bg-neutral-100 dark:bg-neutral-900 border-b border-[var(--foreground)] flex flex-col items-center justify-center gap-1">
             <span className="font-serif text-4xl font-black text-neutral-400 select-none">
               {getHostInitial(link.host)}
@@ -72,22 +69,17 @@ export function LinkCard({ link, categoryLabel, isLoggedIn }: LinkCardProps) {
           </div>
         )}
 
-        {/* 卡片内容区 */}
         <div className="p-4 flex flex-col gap-2 flex-1">
-          {/* 标题 */}
           <h3 className="font-serif text-base font-black leading-snug group-hover:text-[#CC0000] transition-colors line-clamp-2 text-[var(--foreground)]">
             {link.ogTitle ?? link.url}
           </h3>
 
-          {/* OG 描述 / 用户推荐语 */}
           {(link.recommendation || link.ogDescription) && (
             <p className="text-sm text-neutral-600 dark:text-neutral-400 line-clamp-3 leading-relaxed">
-              {/* 用户推荐语优先展示，没有则展示 OG description */}
               {link.recommendation ?? link.ogDescription}
             </p>
           )}
 
-          {/* 分类 badge + 失效标记 */}
           <div className="flex items-center gap-2 flex-wrap mt-auto pt-2">
             {link.category && (
               <Badge
@@ -107,7 +99,6 @@ export function LinkCard({ link, categoryLabel, isLoggedIn }: LinkCardProps) {
             )}
           </div>
 
-          {/* 提交人 + host 来源 */}
           <div className="flex items-center justify-between text-[10px] font-mono text-neutral-400 pt-1">
             <span className="truncate max-w-[60%]">{link.host}</span>
           </div>

app/components/DocsAssistant.tsx

@@ -106,14 +106,12 @@ function DocsAssistantInner({ pageContext }: DocsAssistantProps) {
   );
 
   const [suggestions, setSuggestions] = useState<string[]>([]);
-  // 仅标志后台是否正在获取建议（用于逻辑判断）
   const [isFetchingSuggestions, setIsFetchingSuggestions] = useState(false);
-  // 控制 UI 上是否显示“正在思考...”加载状态（只有主回答结束后，由于建议还在获取，才显示骨架屏）
+  // 仅在主回答结束后、建议仍未返回时展示骨架屏；这与 isFetchingSuggestions 解耦，避免在流式过程中提前出现 loader
   const [showSuggestionsLoader, setShowSuggestionsLoader] = useState(false);
-  // 缓存获取好的建议，等待主回答结束后才推给 Thread 渲染
+  // 先缓存预取建议，等主回答 onFinish 后再推给 Thread，避免与流式回复抢渲染
   const [pendingSuggestions, setPendingSuggestions] = useState<string[]>([]);
 
-  // 欢迎页建议相关的 state
   const [welcomeSuggestions, setWelcomeSuggestions] = useState<
     WelcomeSuggestion[]
   >([]);
@@ -179,7 +177,6 @@ function DocsAssistantInner({ pageContext }: DocsAssistantProps) {
     status: chatStatus,
     messages,
     clearError: clearChatError,
-    // 其他需要的属性...
   } = chat;
 
   // 初次加载欢迎建议的 Effect
@@ -269,7 +266,6 @@ function DocsAssistantInner({ pageContext }: DocsAssistantProps) {
       })();
     }
 
-    // 监控 AI 主流程是否结束：当从 'streaming' 变为 'submitted' / 结束状态时
     const isChatFinished =
       prevStatus === "streaming" &&
       chatStatus !== "streaming" &&

app/components/ZoteroFeed.tsx

@@ -1,8 +1,6 @@
 "use client";
 import * as React from "react";
 
-// Debug helpers (removed in production)
-
 type ZoteroItem = {
   key: string;
   data?: {
@@ -36,7 +34,6 @@ export function ZoteroFeed({
       .then(async (r) => {
         if (!r.ok) throw new Error(`${r.status} ${r.statusText}`);
         const data: ZoteroItem[] = await r.json();
-        // No debug exposure in production
         setItems(data);
       })
       .catch((e: unknown) => {

app/components/assistant-ui/assistant-modal.tsx

@@ -30,8 +30,7 @@ export const AssistantModal: FC<AssistantModalProps> = ({
   isLoadingWelcome,
 }) => {
   const [showBubble, setShowBubble] = useState(false);
-  // 受控状态：允许模态框内部的 X 按钮主动关闭窗口
-  // issue #285: 原先只能靠 Trigger/点击外部/Esc 关闭，用户反馈不知道怎么关窗
+  // 受控 open：让模态框右上角的 X 按钮能主动关闭；非受控时只能靠 Trigger/点外部/Esc
   const [open, setOpen] = useState(false);
 
   const handleCloseModal = useCallback(() => {
@@ -70,7 +69,6 @@ export const AssistantModal: FC<AssistantModalProps> = ({
   return (
     <AssistantModalPrimitive.Root open={open} onOpenChange={setOpen}>
       <AssistantModalPrimitive.Anchor className="aui-root aui-modal-anchor fixed right-4 bottom-4 size-14">
-        {/* 自定义气泡组件 */}
         {showBubble && (
           <div
             className="absolute bottom-17 right-0 z-40 animate-in fade-in-0 slide-in-from-bottom-2 duration-500"
@@ -97,7 +95,6 @@ export const AssistantModal: FC<AssistantModalProps> = ({
         sideOffset={16}
         className="aui-root aui-modal-content relative z-50 h-[500px] w-[400px] overflow-clip rounded-xl border bg-popover p-0 text-popover-foreground shadow-md outline-none data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:slide-out-to-bottom-1/2 data-[state=closed]:slide-out-to-right-1/2 data-[state=closed]:zoom-out data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:slide-in-from-bottom-1/2 data-[state=open]:slide-in-from-right-1/2 data-[state=open]:zoom-in [&>.aui-thread-root]:bg-inherit"
       >
-        {/* 右上角关闭按钮，issue #285：用户找不到关闭模态框的显式入口 */}
         <button
           type="button"
           onClick={handleCloseModal}
@@ -134,17 +131,15 @@ const AssistantModalButton = forwardRef<
   const tooltip = state === "open" ? "Close Assistant" : "Open Assistant";
 
   const handleClick = (e: React.MouseEvent) => {
-    // 当点击open按钮时，关闭气泡对话
     if (onCloseBubble) {
       onCloseBubble();
     }
 
-    // 如果当前是关闭状态，说明即将打开，记录埋点
+    // 仅在 closed → open 时埋点，避免关闭动作也计一次 open
     if (state === "closed" && window.umami) {
       window.umami.track("ai_assistant_open");
     }
 
-    // 继续执行原有的点击事件
     if (rest.onClick) {
       rest.onClick(e);
     }

app/components/assistant-ui/thread.tsx

@@ -45,19 +45,12 @@ export interface WelcomeSuggestion {
 }
 
 interface ThreadProps {
-  // 错误信息
   errorMessage?: string;
-  // 是否显示设置操作按钮
   showSettingsAction?: boolean;
-  // 清除错误的回调函数
   onClearError?: () => void;
-  // AI 生成的后续问题建议
   suggestions?: string[];
-  // 是否正在加载建议
   isLoadingSuggestions?: boolean;
-  // AI 生成的欢迎问题建议
   welcomeSuggestions?: WelcomeSuggestion[];
-  // 是否正在加载欢迎建议
   isLoadingWelcome?: boolean;
 }
 
@@ -70,7 +63,6 @@ export const Thread: FC<ThreadProps> = ({
   welcomeSuggestions,
   isLoadingWelcome,
 }) => {
-  // 控制设置对话框是否打开的状态
   const [isSettingsOpen, setIsSettingsOpen] = useState(false);
 
   const handleSettingsChange = useCallback(
@@ -83,7 +75,6 @@ export const Thread: FC<ThreadProps> = ({
     [onClearError],
   );
 
-  // 打开设置对话框的处理函数
   const handleOpenSettings = useCallback(() => {
     handleSettingsChange(true);
   }, [handleSettingsChange]);
@@ -206,7 +197,6 @@ const ThreadScrollToBottom: FC = () => {
   );
 };
 
-// 欢迎界面组件
 const ThreadWelcome: FC = () => {
   return (
     <ThreadPrimitive.Empty>
@@ -237,7 +227,6 @@ const ThreadWelcome: FC = () => {
   );
 };
 
-// 欢迎页面的初始建议组件
 interface ThreadWelcomeSuggestionsProps {
   suggestions?: WelcomeSuggestion[];
   isLoading?: boolean;
@@ -330,14 +319,12 @@ const ThreadWelcomeSuggestions: FC<ThreadWelcomeSuggestionsProps> = ({
   );
 };
 
-// 输入框组件 Props
 interface ComposerProps {
   isSettingsOpen: boolean;
   onOpenChange: (open: boolean) => void;
   onClearError?: () => void;
 }
 
-// 输入框组件，负责处理用户输入和发送消息
 const Composer: FC<ComposerProps> = ({
   isSettingsOpen,
   onOpenChange,
@@ -366,7 +353,6 @@ const Composer: FC<ComposerProps> = ({
   return (
     <div className="aui-composer-wrapper sticky bottom-0 mx-auto flex w-full max-w-[var(--thread-max-width)] flex-col gap-4 overflow-visible bg-[var(--background)] pb-4 md:pb-6 pt-2 border-t border-[var(--foreground)]">
       <ThreadScrollToBottom />
-      {/* 当没有消息时，显示空状态内容（现已经移到上面的Viewport内以统一滑动，这里可以置空或保留其它用途）*/}
       <ComposerPrimitive.Root
         className="aui-composer-root relative flex w-full flex-col rounded-none border border-[var(--foreground)] bg-[var(--background)] px-1 pt-2 shadow-none"
         aria-disabled={!hasActiveKey}
@@ -418,7 +404,6 @@ interface ComposerActionProps {
   onClearError?: () => void;
 }
 
-// 输入框操作按钮组件（发送、设置、取消）
 const ComposerAction: FC<ComposerActionProps> = ({
   canSend,
   isSettingsOpen,
@@ -660,7 +645,6 @@ const EditComposer: FC = () => {
   );
 };
 
-// 分支切换组件（用于在多次生成的回复之间切换）
 const BranchPicker: FC<BranchPickerPrimitive.Root.Props> = ({
   className,
   ...rest
@@ -691,13 +675,11 @@ const BranchPicker: FC<BranchPickerPrimitive.Root.Props> = ({
   );
 };
 
-// 后续问题建议组件 Props
 interface ThreadFollowupSuggestionsProps {
   suggestions?: string[];
   isLoading?: boolean;
 }
 
-// 后续问题建议组件，显示 AI 生成的建议问题
 const ThreadFollowupSuggestions: FC<ThreadFollowupSuggestionsProps> = ({
   suggestions,
   isLoading,

app/components/rank/HotDocsTab.tsx

@@ -112,7 +112,6 @@ export function HotDocsTab({ initialWindow }: { initialWindow: WindowParam }) {
 
   return (
     <div>
-      {/* 窗口切换 */}
       <div className="flex gap-0 mb-8 border border-[var(--foreground)]">
         {windowOptions.map((opt) => (
           <button
@@ -129,7 +128,6 @@ export function HotDocsTab({ initialWindow }: { initialWindow: WindowParam }) {
         ))}
       </div>
 
-      {/* 加载状态 */}
       {state.status === "loading" && (
         <div className="flex flex-col gap-3">
           {Array.from({ length: 5 }).map((_, i) => (
@@ -141,7 +139,6 @@ export function HotDocsTab({ initialWindow }: { initialWindow: WindowParam }) {
         </div>
       )}
 
-      {/* 错误状态 */}
       {state.status === "error" && (
         <div className="border border-[var(--foreground)] p-8 text-center">
           <p className="font-mono text-sm uppercase tracking-widest text-neutral-500">
@@ -150,7 +147,6 @@ export function HotDocsTab({ initialWindow }: { initialWindow: WindowParam }) {
         </div>
       )}
 
-      {/* 空状态 */}
       {state.status === "ok" && state.docs.length === 0 && (
         <div className="border border-[var(--foreground)] p-8 text-center">
           <p className="font-mono text-sm uppercase tracking-widest text-neutral-500">
@@ -159,7 +155,6 @@ export function HotDocsTab({ initialWindow }: { initialWindow: WindowParam }) {
         </div>
       )}
 
-      {/* 列表 */}
       {state.status === "ok" && state.docs.length > 0 && (
         <div className="flex flex-col gap-3">
           {state.docs.map((doc, idx) => (

scripts/generate-leaderboard.mjs

@@ -4,9 +4,6 @@
  * 结合本地 .source/index.ts 的 docId→title/url 映射 + git log noreply 反推 login，
  * 生成静态 leaderboard 供排行榜页和首页使用。
  *
- * 历史：早期版本直接 prisma 连 Postgres 5432，逼着 DB 端口公网开放。
- * 现已改走后端 endpoint，DB 收回内网。详见 backend PR #22。
- *
  * 用法：
  *   node scripts/generate-leaderboard.mjs
  */