fix(agent/arxiv): 修复 arXiv 检索/状态机/错误处理等核心体验问题

.gitignore

@@ -29,6 +29,10 @@ htmlcov/
 # Environment
 .env
 
+# Worktrees
+.worktrees/
+worktrees/
+
 # AI agent config (local only)
 .claude/
 CLAUDE.md

README.md

@@ -88,6 +88,17 @@ PaperMind 是一个面向科研工作者的 AI 增强平台，帮你从「搜索
 
 ## ✨ 核心能力
 
+### 🧠 认知重构工作流 (PaperSenseMaking)
+
+「阅读→理解→重构」的完整论文工作流：
+
+- 📝 **Act 1 理解** —— 摘要 + 关键发现，厘清论文核心
+- ⚡ **Act 2 碰撞** —— 冲突 + 疑问，与已有知识对话
+- 🔄 **Act 3 重构** —— 前后对比 + 认知变化，形成新认知
+- 📖 **全文对照翻译** —— 段落级中英对照，支持两种模式
+  - ⚡ **快速翻译**：1-2 分钟，PyMuPDF 分段 + 并发翻译
+  - 📐 **布局保留**：3-5 分钟，PDFMathTranslate 完整排版（公式/图表保留）
+
 ### 🤖 AI Agent 对话
 
 你的智能研究助理，自然语言交互搞定一切：
@@ -162,6 +173,21 @@ PaperMind 是一个面向科研工作者的 AI 增强平台，帮你从「搜索
 - 🎫 **JWT Token** —— 7 天有效期，自动续期
 - 🛡️ **全站保护** —— 所有 API 都需要认证
 
+### ⚙️ LLM 模型管理
+
+灵活控制成本，按场景分配模型：
+
+- 📊 **统一配置** —— 默认使用 GLM-4.7（文本）+ GLM-4.6V（视觉）
+- 🔄 **一键切换** —— 在设置页面随时切换配置
+- 🎯 **场景映射** —— 所有文本任务自动使用 GLM-4.7
+- 💰 **成本优化** —— 单一模型配置，避免管理复杂度
+- 📈 **Token 追踪** —— 所有 API 调用自动记录成本和用量
+
+**默认模型配置**：
+- 文本任务（粗读/精读/翻译/写作）：GLM-4.7
+- 视觉任务（图表分析/OCR）：GLM-4.6V
+- 降级备用：GLM-4.7
+
 ---
 
 ## 🏗️ 架构总览
@@ -384,6 +410,7 @@ alembic upgrade head
 - **[Semantic Scholar](https://www.semanticscholar.org)** — 引用数据来源
 - **[CSFeeds](https://csarxiv.org)** — 论文源订阅服务
 - **[learn-claude-code](https://github.com/shareAI-lab/learn-claude-code)** — Agent Harness 工程体系启发，s01-s12 渐进式解构：Loop → Tools → Planning → Subagents → Skills → Context → Tasks → Background → Teams → Protocols → Autonomous
+- **[PaperSenseMaking](https://github.com/edu-ai-builders/paper-sense-making)** — 论文阅读「阅读→理解→重构」工作流设计灵感
 
 ---
 

apps/api/main.py

@@ -155,10 +155,13 @@ async def app_error_handler(_request: Request, exc: AppError):
     cs_feeds,
     graph,
     jobs,
+    llm_configs,
     papers,
     pipelines,
+    sensemaking,
     system,
     topics,
+    translate,
     writing,
 )
 from apps.api.routers import (
@@ -177,3 +180,6 @@ async def app_error_handler(_request: Request, exc: AppError):
 app.include_router(writing.router)
 app.include_router(jobs.router)
 app.include_router(auth.router)
+app.include_router(sensemaking.router)
+app.include_router(translate.router)
+app.include_router(llm_configs.router)

apps/api/routers/llm_configs.py

@@ -0,0 +1,222 @@
+"""
+LLM 模型管理路由 - 配置管理 + 场景化切换
+"""
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+from packages.storage.db import session_scope
+from packages.storage.repositories import LLMConfigRepository
+
+router = APIRouter(prefix="/llm-configs", tags=["llm-configs"])
+
+
+class LLMConfigItem(BaseModel):
+    id: str
+    name: str
+    provider: str
+    api_base_url: str | None
+    model_skim: str
+    model_deep: str
+    model_vision: str | None
+    model_embedding: str
+    model_fallback: str
+    is_active: bool
+
+
+class LLMConfigCreate(BaseModel):
+    name: str = Field(..., description="配置名称")
+    provider: str = Field(..., description="提供商：zhipu/openai/anthropic/siliconflow")
+    api_key: str = Field(..., description="API Key")
+    api_base_url: str | None = Field(None, description="自定义 API Base URL")
+    model_skim: str = Field(..., description="粗读/简单任务模型")
+    model_deep: str = Field(..., description="精读/复杂任务模型")
+    model_vision: str | None = Field(None, description="视觉模型")
+    model_embedding: str = Field(..., description="嵌入模型")
+    model_fallback: str = Field(..., description="降级备用模型")
+
+
+class LLMConfigUpdate(BaseModel):
+    name: str | None = None
+    provider: str | None = None
+    api_key: str | None = None
+    api_base_url: str | None = None
+    model_skim: str | None = None
+    model_deep: str | None = None
+    model_vision: str | None = None
+    model_embedding: str | None = None
+    model_fallback: str | None = None
+
+
+class LLMConfigActivate(BaseModel):
+    config_id: str
+
+
+class LLMConfigList(BaseModel):
+    configs: list[LLMConfigItem]
+    active_id: str | None
+
+
+class LLMConfigDetail(BaseModel):
+    config: LLMConfigItem
+
+
+@router.get("", response_model=LLMConfigList)
+def list_configs():
+    """获取所有 LLM 配置列表"""
+    with session_scope() as session:
+        repo = LLMConfigRepository(session)
+        configs = repo.list_all()
+        active_cfg = repo.get_active()
+        return LLMConfigList(
+            configs=[
+                LLMConfigItem(
+                    id=c.id,
+                    name=c.name,
+                    provider=c.provider,
+                    api_base_url=c.api_base_url,
+                    model_skim=c.model_skim,
+                    model_deep=c.model_deep,
+                    model_vision=c.model_vision,
+                    model_embedding=c.model_embedding,
+                    model_fallback=c.model_fallback,
+                    is_active=c.is_active,
+                )
+                for c in configs
+            ],
+            active_id=active_cfg.id if active_cfg else None,
+        )
+
+
+@router.get("/{config_id}", response_model=LLMConfigDetail)
+def get_config(config_id: str):
+    """获取单个配置详情"""
+    with session_scope() as session:
+        repo = LLMConfigRepository(session)
+        try:
+            cfg = repo.get_by_id(config_id)
+        except ValueError as e:
+            raise HTTPException(status_code=404, detail=str(e)) from e
+        return LLMConfigDetail(
+            config=LLMConfigItem(
+                id=cfg.id,
+                name=cfg.name,
+                provider=cfg.provider,
+                api_base_url=cfg.api_base_url,
+                model_skim=cfg.model_skim,
+                model_deep=cfg.model_deep,
+                model_vision=cfg.model_vision,
+                model_embedding=cfg.model_embedding,
+                model_fallback=cfg.model_fallback,
+                is_active=cfg.is_active,
+            )
+        )
+
+
+@router.post("", response_model=LLMConfigDetail)
+def create_config(req: LLMConfigCreate):
+    """创建新的 LLM 配置"""
+    with session_scope() as session:
+        repo = LLMConfigRepository(session)
+        cfg = repo.create(
+            name=req.name,
+            provider=req.provider,
+            api_key=req.api_key,
+            api_base_url=req.api_base_url,
+            model_skim=req.model_skim,
+            model_deep=req.model_deep,
+            model_vision=req.model_vision,
+            model_embedding=req.model_embedding,
+            model_fallback=req.model_fallback,
+        )
+        session.commit()
+        return LLMConfigDetail(
+            config=LLMConfigItem(
+                id=cfg.id,
+                name=cfg.name,
+                provider=cfg.provider,
+                api_base_url=cfg.api_base_url,
+                model_skim=cfg.model_skim,
+                model_deep=cfg.model_deep,
+                model_vision=cfg.model_vision,
+                model_embedding=cfg.model_embedding,
+                model_fallback=cfg.model_fallback,
+                is_active=cfg.is_active,
+            )
+        )
+
+
+@router.patch("/{config_id}", response_model=LLMConfigDetail)
+def update_config(config_id: str, req: LLMConfigUpdate):
+    """更新配置"""
+    with session_scope() as session:
+        repo = LLMConfigRepository(session)
+        try:
+            cfg = repo.update(
+                config_id,
+                name=req.name,
+                provider=req.provider,
+                api_key=req.api_key,
+                api_base_url=req.api_base_url,
+                model_skim=req.model_skim,
+                model_deep=req.model_deep,
+                model_vision=req.model_vision,
+                model_embedding=req.model_embedding,
+                model_fallback=req.model_fallback,
+            )
+        except ValueError as e:
+            raise HTTPException(status_code=404, detail=str(e)) from e
+        session.commit()
+        return LLMConfigDetail(
+            config=LLMConfigItem(
+                id=cfg.id,
+                name=cfg.name,
+                provider=cfg.provider,
+                api_base_url=cfg.api_base_url,
+                model_skim=cfg.model_skim,
+                model_deep=cfg.model_deep,
+                model_vision=cfg.model_vision,
+                model_embedding=cfg.model_embedding,
+                model_fallback=cfg.model_fallback,
+                is_active=cfg.is_active,
+            )
+        )
+
+
+@router.delete("/{config_id}")
+def delete_config(config_id: str):
+    """删除配置（不能删除当前激活的配置）"""
+    with session_scope() as session:
+        repo = LLMConfigRepository(session)
+        cfg = repo.get_by_id(config_id)
+        if cfg.is_active:
+            raise HTTPException(status_code=400, detail="不能删除当前激活的配置")
+        repo.delete(config_id)
+        session.commit()
+        return {"message": "删除成功"}
+
+
+@router.post("/activate", response_model=LLMConfigDetail)
+def activate_config(req: LLMConfigActivate):
+    """激活指定配置"""
+    with session_scope() as session:
+        repo = LLMConfigRepository(session)
+        try:
+            cfg = repo.activate(req.config_id)
+        except ValueError as e:
+            raise HTTPException(status_code=404, detail=str(e)) from e
+        session.commit()
+        return LLMConfigDetail(
+            config=LLMConfigItem(
+                id=cfg.id,
+                name=cfg.name,
+                provider=cfg.provider,
+                api_base_url=cfg.api_base_url,
+                model_skim=cfg.model_skim,
+                model_deep=cfg.model_deep,
+                model_vision=cfg.model_vision,
+                model_embedding=cfg.model_embedding,
+                model_fallback=cfg.model_fallback,
+                is_active=cfg.is_active,
+            )
+        )

apps/api/routers/papers.py

@@ -324,6 +324,59 @@ def serve_paper_pdf(paper_id: UUID) -> FileResponse:
     )
 
 
+@router.get("/papers/{paper_id}/segments")
+def get_paper_segments(paper_id: UUID) -> dict:
+    """获取论文分段（用于全文对照翻译）- 包含页码信息"""
+    with session_scope() as session:
+        repo = PaperRepository(session)
+        try:
+            paper = repo.get_by_id(paper_id)
+        except ValueError as exc:
+            raise HTTPException(status_code=404, detail=str(exc)) from exc
+        pdf_path = paper.pdf_path
+
+    if not pdf_path:
+        raise HTTPException(status_code=404, detail="论文没有 PDF 文件")
+
+    full_path = Path(pdf_path)
+    if not full_path.exists():
+        raise HTTPException(status_code=404, detail="PDF 文件不存在")
+
+    try:
+        import fitz
+
+        doc = fitz.open(str(full_path))
+        paragraphs: list[dict] = []
+        para_idx = 0
+        max_pages = 30
+
+        for page_num in range(min(max_pages, len(doc))):
+            page = doc.load_page(page_num)
+            page_text = page.get_text("text").strip()
+            if not page_text:
+                continue
+
+            blocks = page_text.split("\n\n")
+            for block in blocks:
+                block = block.strip()
+                if len(block) < 20:
+                    continue
+                para_idx += 1
+                paragraphs.append(
+                    {
+                        "id": f"p-{para_idx}",
+                        "type": "paragraph",
+                        "content": block[:2000],
+                        "pageNumber": page_num + 1,
+                    }
+                )
+
+        doc.close()
+        return {"segments": paragraphs}
+    except Exception as e:
+        return {"segments": [], "error": str(e)}
+
+
 @router.post("/papers/{paper_id}/ai/explain")
 def ai_explain_text(paper_id: UUID, body: AIExplainReq) -> dict:
     """AI 解释/翻译选中文本"""