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

[Color2333]

Summary

从一次真实使用记录定位到全链路多处核心 bug，本次一并修复：arXiv 搜不到经典论文、入库状态机「成功+过期」矛盾、Cloudflare 504 HTML 甩用户脸上、入库前看不到论文标题等。11 个文件，+364/-112。

问题与修复

后端 - arXiv 检索

• arxiv_client.py 补 import time（重试分支原本会 NameError 崩）
• fetch_latest 默认 days_back=0 —— 原 7 天过滤把 OpenShape/Uni3D/PointContrast 等经典论文全筛掉
• _build_arxiv_query 拆词上限 3→6；新增引号精确短语搜索
• /ingest/arxiv 路由暴露 days_back 参数（默认 0），前端 ingestApi.arxiv 同步
• search_arxiv Agent 工具暴露 days_back / sort_by（默认 relevance）

后端 - Agent 状态机

• 新增 _HANDLED_ACTION_CACHE（TTL 1h 内存缓存）做 confirm/reject 幂等保护
• 找不到 action 时区分文案：「已处理过」vs「真的过期」，消除矛盾提示
• SYSTEM_PROMPT 强化：ingest_arxiv 前必须列出候选标题/作者/年份，禁止盲 ID 确认

前端 - 错误处理

• services/api.ts 新增 friendlyStatusMessage + extractErrorMessage
• request / fetchSSE 响应非 JSON 或以 < / <!doctype 开头一律按状态码降级文案
• 504/524/408/502/503 全部有对应中文提示，Cloudflare HTML 错误页不再甩用户
• errorHandler.ts 补 504/524/408 识别 + HTML 污染兜底

前端 - Agent 交互

• AgentSessionContext 新增 handledActionsRef，防双击/StrictMode 重复提交
• ActionConfirmCard 特化 ingest_arxiv：反查 search_arxiv 候选，显示标题+作者卡片

顺带修复

• PaperDetail.tsx 精读结果错塞 savedDeep（真 bug，导致精读后界面空白）
• AggregationPanel / Collect 多源搜索字段不匹配（sources vs source）
• 清理 agent_tools.py Iterator TYPE_CHECKING / set comprehension / 重复字典 key
• 清理多处 unused import

真实端到端验证

查询	修前	修后	证据
OpenShape	0	2 篇	2305.10764 OpenShape (NeurIPS'23)
Uni3D	0	5 篇全命中	2310.06773 Uni3D (ICLR'24)
ULIP-2	0	1 篇	2305.08275 ULIP-2 原版
PointContrast	0	3 篇	2007.10985 PointContrast 原版
Point-MAE	0	4 篇	2203.06604 Point-MAE
ShapeNet	0	5 篇	1512.03012 ShapeNet 经典原版

Test plan

• npx tsc --noEmit 前端 0 错误
• npx vite build 生产构建通过（2.5s）
• python -m py_compile 后端 3 个改动文件通过
• pre-commit hooks（ruff / ruff-format / 各通用检查）全绿
• 后端模块导入 + 状态机幂等缓存单元测试通过
• 真实 HTTP 端到端调用 /ingest/arxiv?query=X 对 6 个经典查询全部命中
• 浏览器端 UX 验收（504 错误降级 / 入库卡片新展示 / 精读分模块显示 / 双击 confirm 不再"已过期"）— 建议 merge 前人肉过一遍

🤖 Generated with Claude Code

[github-actions]

🔍 OpenCode PR Review Required

这是一个受保护的分支，merge 前需要进行 code review。

请运行以下命令进行 OpenCode review：

/oc review https://github.com/Color2333/PaperMind/pull/$PR_NUM

或者在 PR 页面评论 /oc 来触发 OpenCode review。

---

This is an automated reminder from PR Review Gate.

[Color2333]

/oc review

[opencode-agent]

Good! The TypeScript deprecation warning is not a real error. Now let me provide my review:

Code Review Summary

这是一个高质量的 bug fix PR，修复了从真实使用中发现的 11 个核心问题。以下是详细评审：

✅ 主要修复

1. arXiv 检索问题 (packages/integrations/arxiv_client.py)

• ✅ 补充 import time（重试分支原本会 NameError）
• ✅ fetch_latest 默认 days_back=0，解决经典论文被过滤问题
• ✅ _build_arxiv_query 拆词上限 3→6，新增引号精确短语搜索
• ✅ /ingest/arxiv 路由和前端 API 同步暴露 days_back 参数
• ✅ search_arxiv Agent 工具暴露 days_back / sort_by

代码质量: 逻辑清晰，日期过滤回退机制处理得当（500 错误时自动去掉日期重试）

2. Agent 状态机幂等保护 (packages/ai/agent_service.py)

• ✅ 新增 _HANDLED_ACTION_CACHE（TTL 1h）防止重复 confirm/reject
• ✅ 区分「已处理过」vs「真过期」文案，消除矛盾提示
• ✅ SYSTEM_PROMPT 强化：ingest_arxiv 前必须列出候选标题/作者/年份

代码质量: 缓存清理机制完善（超过 256 条目自动清理过期项）

3. 前端错误处理 (frontend/src/services/api.ts, errorHandler.ts)

• ✅ 新增 friendlyStatusMessage + extractErrorMessage
• ✅ 非 JSON/HTML 响应降级处理（解决 Cloudflare 504 HTML 错误页）
• ✅ 504/524/408/502/503 全部有对应中文提示

代码质量: 错误提取逻辑健壮，考虑了 JSON 解析失败/HTML 污染/超长文本等边界情况

4. Agent 交互优化 (frontend/src/contexts/AgentSessionContext.tsx)

• ✅ 新增 handledActionsRef 防双击/StrictMode 重复提交
• ✅ ActionConfirmCard 特化 ingest_arxiv：反查 search_arxiv 候选，显示标题 + 作者卡片

代码质量: lookupArxivCandidates 函数设计巧妙，从对话历史反向查找元信息

5. PaperDetail 修复 (frontend/src/pages/PaperDetail.tsx)

• ✅ 精读结果正确存入 savedDeep（原 bug 错塞 savedDeep 导致界面空白）

⚠️ 潜在问题

1. agent_tools.py:1017 并发处理

def _process_one(pid_str: str) -> tuple[bool, bool]:
    """单篇论文：embed ∥ skim 并行"""
    pid = UUID(pid_str)
    e_ok, s_ok = False, False
    with ThreadPoolExecutor(max_workers=2) as inner:  # ⚠️ 每次创建新线程池
        fe = inner.submit(pipelines.embed_paper, pid)
        fs = inner.submit(pipelines.skim, pid)
        ...

建议: 外层已创建 ThreadPoolExecutor(max_workers=PAPER_CONCURRENCY)，内层无需再创建线程池，可直接顺序调用或使用 asyncio.gather

2. arxiv_client.py:205 重复字典 key

{"code": "cs.CL", "name": "Computational Linguistics", "description": ""},
# 与上方的 cs.CL (Computation and Language) 重复

影响: 后者覆盖前者，实际不影响功能（都是 cs.CL 分类）

3. agent_service.py:328 竞态条件

if not action:
    already_handled = _is_action_handled(confirmed_action_id)
    err_msg = (...)

风险: 多线程环境下 _HANDLED_ACTION_CACHE 可能并发访问，但考虑 Python GIL 和 TTL 设计，实际风险较低

📊 测试覆盖

• ✅ npx tsc --noEmit 前端 0 错误
• ✅ python -m py_compile 后端 3 个文件通过
• ✅ 端到端验证：6 个经典查询（OpenShape/Uni3D/ULIP-2/PointContrast/Point-MAE/ShapeNet）全部命中

🎯 关键改进验证

问题	修复前	修复后	证据
OpenShape 检索	0 篇	2 篇	2305.10764 NeurIPS'23
Uni3D 检索	0 篇	5 篇	2310.06773 ICLR'24
Cloudflare 504	甩 HTML 页	中文提示	friendlyStatusMessage
重复 confirm	"已过期"矛盾	"已处理过"	_HANDLED_ACTION_CACHE

📝 建议

1. 高优先级: 修复 agent_tools.py:1017 嵌套线程池问题（性能优化）
2. 中优先级: 清理 arxiv_client.py 重复的 cs.CL 分类
3. 低优先级: 考虑为 _HANDLED_ACTION_CACHE 添加线程锁（可选）

✅ Review 结论: LGTM (Look Good To Merge)

核心 bug 修复到位，错误处理健壮，端到端验证充分。建议合并后人肉过一遍前端 UX（504 降级/入库卡片/精读显示）。

opencode session  |  github run

[github-actions]

🔍 OpenCode PR Review Required

这是一个受保护的分支，merge 前需要进行 code review。

请运行以下命令进行 OpenCode review：

/oc review https://github.com/Color2333/PaperMind/pull/$PR_NUM

或者在 PR 页面评论 /oc 来触发 OpenCode review。

---

This is an automated reminder from PR Review Gate.

[Color2333]

感谢 review！逐条回应：

✅ 已处理

• [中优] arxiv_client.py cs.CL 重复分类 → 已在 commit fcc241a 删除重复项（官方 arxiv 只有一个 cs.CL = Computation and Language）

⏸ 保留现状（带理由）

[高优] agent_tools.py:1017 嵌套线程池：review 建议"直接顺序调用或 asyncio.gather"，但这里 embed_paper 和 skim 都是 IO-bound 的 LLM 长调用（每个几秒到几十秒），内层并行能让单篇论文快 ~2×；改顺序会让整体流程变慢。ThreadPoolExecutor(max_workers=2) 创建/销毁开销 < 50ms，占比可忽略。且此代码不在本 PR 变更范围（_process_one 函数未改动），按 KISS/YAGNI 不在这次动它。

[低优] _HANDLED_ACTION_CACHE 线程锁：review 自己也指出"Python GIL 和 TTL 设计，实际风险较低"。Python dict 的 get / __setitem__ / pop 对单 key 都是 GIL-atomic，TTL 是 "stale 即惰性清理" 的最终一致模型，竞态窗口内最坏结果只是多一次误判（复查一次 DB）而已，无数据损坏风险。加锁会增加每次 Agent 对话的锁竞争开销，不值得。

合并前再本地跑了一次 smoke 确认删分类没破坏 fetch_categories() 逻辑。