readloops 2.3.0__tar.gz → 2.3.1__tar.gz

{readloops-2.3.0 → readloops-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: readloops
-Version: 2.3.0
+Version: 2.3.1
 Summary: AI 驱动的英语阅读训练器：可理解输入 + FSRS 间隔重复
 Author: Fangyuan2711
 License: MIT
@@ -38,9 +38,22 @@ Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
 Requires-Dist: pre-commit>=3.7; extra == "dev"
 Dynamic: license-file
 
-# ReadLoops
+<p align="center">
+  <img src="https://raw.githubusercontent.com/pekoqq/ReadLoops/main/assets/logo.png" width="104" alt="ReadLoops logo">
+</p>
 
-> AI 驱动的英语阅读训练器。基于「可理解输入（i+1）」+ 阅读驱动的 FSRS 间隔重复，面向大学英语四级（进阶六级）。
+<h1 align="center">ReadLoops</h1>
+
+<p align="center">
+  <a href="https://pypi.org/project/readloops/"><img alt="PyPI" src="https://img.shields.io/pypi/v/readloops"></a>
+  <a href="https://pypi.org/project/readloops/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/readloops"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green"></a>
+  <a href="https://github.com/pekoqq/ReadLoops/releases"><img alt="Release" src="https://img.shields.io/github/v/release/pekoqq/ReadLoops"></a>
+</p>
+
+<p align="center">
+  AI 驱动的英语阅读训练器。基于「可理解输入（i+1）」+ 阅读驱动的 FSRS 间隔重复，面向大学英语四级（进阶六级）。
+</p>
 
 ## 它解决什么问题
 

{readloops-2.3.0 → readloops-2.3.1}/README.md

@@ -1,6 +1,19 @@
-# ReadLoops
-
-> AI 驱动的英语阅读训练器。基于「可理解输入（i+1）」+ 阅读驱动的 FSRS 间隔重复，面向大学英语四级（进阶六级）。
+<p align="center">
+  <img src="https://raw.githubusercontent.com/pekoqq/ReadLoops/main/assets/logo.png" width="104" alt="ReadLoops logo">
+</p>
+
+<h1 align="center">ReadLoops</h1>
+
+<p align="center">
+  <a href="https://pypi.org/project/readloops/"><img alt="PyPI" src="https://img.shields.io/pypi/v/readloops"></a>
+  <a href="https://pypi.org/project/readloops/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/readloops"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green"></a>
+  <a href="https://github.com/pekoqq/ReadLoops/releases"><img alt="Release" src="https://img.shields.io/github/v/release/pekoqq/ReadLoops"></a>
+</p>
+
+<p align="center">
+  AI 驱动的英语阅读训练器。基于「可理解输入（i+1）」+ 阅读驱动的 FSRS 间隔重复，面向大学英语四级（进阶六级）。
+</p>
 
 ## 它解决什么问题
 

{readloops-2.3.0 → readloops-2.3.1}/app/api/words.py

@@ -1,7 +1,9 @@
 """单词路由：查词、生词本、批量添加。"""
+import asyncio
 import time
 
 from fastapi import APIRouter
+from fastapi.responses import JSONResponse
 from pydantic import BaseModel
 
 from app.database import get_db
@@ -42,11 +44,22 @@ class TranslateRequest(BaseModel):
 async def translate(req: TranslateRequest):
     """翻译句子 / 短语。
 
-    划词选中多个单词时走这里 —— 词典查不到整句，
-    以前会直接显示「查询失败」。
+    划词选中多个单词时走这里 —— 词典查不到整句，需要调 AI。
+    AI 调用是同步阻塞的，放到线程池避免卡住事件循环；失败返回 502 与原因，
+    前端据此提示「点击重试」而不是笼统的「翻译失败」。
     """
-    translation = translate_sentence(req.text)
-    return {"text": req.text, "translation": translation, "ok": bool(translation)}
+    text = (req.text or "").strip()
+    if not text:
+        return {"text": "", "translation": "", "ok": False, "error": "选中文本为空"}
+    try:
+        translation = await asyncio.to_thread(translate_sentence, text)
+    except Exception as exc:
+        return JSONResponse(
+            status_code=502,
+            content={"text": text, "translation": "", "ok": False,
+                     "error": f"AI 服务暂时不可用：{str(exc)[:160]}"},
+        )
+    return {"text": text, "translation": translation, "ok": bool(translation)}
 
 
 @router.post("/add")

{readloops-2.3.0 → readloops-2.3.1}/app/main.py

@@ -1,5 +1,6 @@
 """FastAPI 入口。"""
 import re
+from importlib import metadata
 
 from fastapi import FastAPI
 from fastapi.responses import FileResponse, HTMLResponse
@@ -8,7 +9,12 @@ from fastapi.staticfiles import StaticFiles
 from app.api import articles, reading, stats, words
 from app.config import WEB_DIR
 
-app = FastAPI(title="ReadLoops", version="2.2.1")
+try:
+    __version__ = metadata.version('readloops')
+except metadata.PackageNotFoundError:  # 源码直接运行、未 pip install 时
+    __version__ = '0.0.0.dev'
+
+app = FastAPI(title="ReadLoops", version=__version__)
 
 # 注册路由
 app.include_router(articles.router)
@@ -53,9 +59,25 @@ async def manifest():
     return FileResponse(str(WEB_DIR / "manifest.json"))
 
 
-@app.get("/icon.svg")
+@app.get("/icon.svg", include_in_schema=False)
 async def icon():
-    return FileResponse(str(WEB_DIR / "icon.svg"))
+    return FileResponse(str(WEB_DIR / "icon.svg"), headers={"Cache-Control": "no-cache"})
+
+
+# favicon / iOS 主屏 / PWA 各尺寸 PNG（与 manifest.json 中的路径对应）
+_ICON_ROUTES = {
+    '/favicon.ico': 'favicon.ico',
+    '/favicon-16.png': 'favicon-16.png',
+    '/favicon-32.png': 'favicon-32.png',
+    '/apple-touch-icon.png': 'apple-touch-icon.png',
+    '/icon-192.png': 'icon-192.png',
+    '/icon-512.png': 'icon-512.png',
+    '/icon-maskable-512.png': 'icon-maskable-512.png',
+}
+for _url, _fname in _ICON_ROUTES.items():
+    def _icon_endpoint(_fname: str = _fname):
+        return FileResponse(str(WEB_DIR / _fname), headers={"Cache-Control": "no-cache"})
+    app.get(_url, include_in_schema=False)(_icon_endpoint)
 
 
 @app.get("/api/health")

{readloops-2.3.0 → readloops-2.3.1}/app/services/ai.py

@@ -22,29 +22,49 @@ def _get_settings():
     }
 
 
-def _chat(messages, max_tokens=1500, temperature=0.7):
-    """调用 AI 聊天接口，关闭思考模式。"""
+def _chat(messages, max_tokens=1500, temperature=0.7, retries=2):
+    """调用 AI 聊天接口，关闭思考模式。
+
+    deepseek-flash 等模型偶发：① 网络抖动 / 5xx；② 思考没被关住，正文为空、
+    内容落到 reasoning_content。两类都按可恢复错误处理，最多重试 ``retries`` 次。
+    """
     cfg = _get_settings()
     if not cfg["api_key"]:
         raise ValueError("未配置 API Key")
-    resp = httpx.post(
-        f"{cfg['base_url'].rstrip('/')}/chat/completions",
-        headers={
-            "Authorization": f"Bearer {cfg['api_key']}",
-            "Content-Type": "application/json",
-        },
-        json={
-            "model": cfg["model"],
-            "messages": messages,
-            "max_tokens": max_tokens,
-            "temperature": temperature,
-            "thinking": {"type": "disabled"},
-        },
-        timeout=60,
-    )
-    resp.raise_for_status()
-    data = resp.json()
-    return data["choices"][0]["message"]["content"]
+    last_exc = None
+    for attempt in range(retries + 1):
+        try:
+            resp = httpx.post(
+                f"{cfg['base_url'].rstrip('/')}/chat/completions",
+                headers={
+                    "Authorization": f"Bearer {cfg['api_key']}",
+                    "Content-Type": "application/json",
+                },
+                json={
+                    "model": cfg["model"],
+                    "messages": messages,
+                    "max_tokens": max_tokens,
+                    "temperature": temperature,
+                    "thinking": {"type": "disabled"},
+                },
+                timeout=60,
+            )
+            resp.raise_for_status()
+            data = resp.json()
+            message = data["choices"][0]["message"]
+            content = (message.get("content") or "").strip()
+            if not content:
+                # 正文为空通常是思考泄漏到 reasoning_content —— 关思考没生效，值得重试
+                reasoning = (message.get("reasoning_content") or "").strip()
+                raise ValueError(f"AI 返回内容为空（reasoning_content {len(reasoning)} 字）")
+            return content
+        except Exception as exc:  # 网络 / HTTP / 空内容都走重试
+            last_exc = exc
+            if attempt < retries:
+                time.sleep(0.6 * (attempt + 1))
+                continue
+            raise
+    raise last_exc
 
 
 def _extract_json(text):
@@ -563,9 +583,5 @@ def translate_sentence(text):
 Return ONLY the translation itself — no explanation, no quotes, no pinyin.
 
 Text: {text}"""
-    try:
-        result = _chat([{"role": "user", "content": prompt}], max_tokens=500, temperature=0.3)
-        return (result or "").strip().strip('"').strip("'")
-    except Exception as e:
-        print(f"翻译失败: {e}")
-        return ""
+    result = _chat([{"role": "user", "content": prompt}], max_tokens=500, temperature=0.3)
+    return (result or "").strip().strip('"').strip("'")

{readloops-2.3.0 → readloops-2.3.1}/app/web/css/style.css

@@ -51,6 +51,8 @@
      玻璃会显得很平；加入极淡光斑后，模糊才产生真正的层次感。 */
   --ambient-1: rgba(140,130,255,0.07);
   --ambient-2: rgba(255,160,100,0.045);
+  /* 专注模式：四周收暗的暗角色（把视线收向中央阅读卡），各主题单独配浓度 */
+  --focus-shade: rgba(0,0,0,0.42);
 
   /* ===== 按钮设计系统 =====
      全站按钮共用这套 token。之前每个按钮各写各的，
@@ -217,6 +219,7 @@
   --ripple-color: rgba(60,45,20,0.12);
   --ambient-1: rgba(190,150,70,0.12);
   --ambient-2: rgba(130,95,50,0.07);
+  --focus-shade: rgba(58,42,18,0.26);
 }
 
 /* 明亮 — 柔和米白，不刺眼 */
@@ -236,6 +239,7 @@
   --ripple-color: rgba(0,0,0,0.11);
   --ambient-1: rgba(120,140,255,0.08);
   --ambient-2: rgba(255,180,120,0.07);
+  --focus-shade: rgba(35,38,52,0.15);
 }
 
 /* 纯黑 */
@@ -255,6 +259,7 @@
   --ripple-color: rgba(255,255,255,0.08);
   --ambient-1: rgba(140,130,255,0.09);
   --ambient-2: rgba(255,160,100,0.055);
+  --focus-shade: rgba(0,0,0,0.58);
 }
 
 * { margin: 0; padding: 0; box-sizing: border-box; }
@@ -270,17 +275,67 @@ body {
   font-size: 13px;
 }
 
-/* 氛围光层：固定在最底层，为毛玻璃提供可折射的内容 */
-body::before {
+/* 氛围光层：两团极淡光斑固定在最底层，为毛玻璃提供可折射内容。
+   拆成两个独立伪元素、用 transform 平移 —— CSS 渐变的圆心坐标无法平滑过渡，
+   只有 transform 能让光源「滑动」。
+   日常：左上冷光 + 右下暖光的对角光；进入专注：两团光平滑上移、在顶部汇聚成顶光。
+   过渡延迟 .3s、持续 3s，与水纹涟漪（setTimeout 300 + rippleWave 3s）同时起落。 */
+body::before, body::after {
   content: '';
+  position: fixed;
+  left: 0;
+  top: 0;
+  width: 64vw;
+  height: 64vh;
+  z-index: -1; /* 严格压在所有内容之下、body 底色之上的背景光层 */
+  pointer-events: none;
+  will-change: transform, filter, opacity;
+  filter: brightness(1);
+  opacity: 1;
+  transition: transform 0.6s var(--ease-out), filter 0.6s var(--ease-out),
+              opacity 0.6s var(--ease-out); /* 退出时跟手回位 */
+}
+body::before {
+  background: radial-gradient(closest-side, var(--ambient-1), transparent 72%);
+  transform: translate(-16vw, -22vh); /* 光斑中心≈视口 16% / 10% */
+}
+body::after {
+  background: radial-gradient(closest-side, var(--ambient-2), transparent 72%);
+  transform: translate(54vw, 58vh); /* 光斑中心≈视口 86% / 90% */
+}
+/* 进入专注：只留一整团统一的顶光居中铺在上方（放大一圈），另一团对角光淡出，
+   避免顶部出现两个冷暖异色的「球」。延迟 .3s、时长 3s，与水纹涟漪同时落定。 */
+body.focus-mode::before {
+  transform: translate(18vw, -38vh) scale(1.7);
+  filter: brightness(2.6);
+  transition: transform 3s 0.3s cubic-bezier(0.16, 1, 0.3, 1),
+              filter 3s 0.3s cubic-bezier(0.16, 1, 0.3, 1);
+}
+body.focus-mode::after {
+  opacity: 0; /* 第二团光淡出，顶部只剩一团 */
+  transition: opacity 2.4s 0.3s var(--ease-out);
+}
+@media (prefers-reduced-motion: reduce) {
+  body.focus-mode::before, body.focus-mode::after { transition-duration: 0.01s; transition-delay: 0s; }
+}
+
+/* 专注聚焦暗角：中央（阅读卡所在）保持通透，向四周、底部轻微压暗，收束视线。
+   层级：背景光 -1 < 暗角 0 < 应用内容 .app(1)。 */
+.focus-shade {
   position: fixed;
   inset: 0;
   z-index: 0;
   pointer-events: none;
-  background:
-    radial-gradient(58% 48% at 16% 10%, var(--ambient-1), transparent 68%),
-    radial-gradient(52% 46% at 86% 90%, var(--ambient-2), transparent 70%);
-  transition: background 0.4s ease;
+  opacity: 0;
+  background: radial-gradient(118% 82% at 50% 38%, transparent 50%, var(--focus-shade) 100%);
+  transition: opacity 0.6s var(--ease-out);
+}
+body.focus-mode .focus-shade {
+  opacity: 1;
+  transition: opacity 3s 0.3s cubic-bezier(0.16, 1, 0.3, 1); /* 与涟漪、顶光同时落定 */
+}
+@media (prefers-reduced-motion: reduce) {
+  body.focus-mode .focus-shade { transition-duration: 0.01s; transition-delay: 0s; }
 }
 
 /* 主题切换过渡：只在切换的那 420ms 内生效（JS 临时加类），
@@ -299,6 +354,8 @@ body.theme-transition *::after {
 /* 布局 */
 .app {
   display: flex;
+  position: relative;
+  z-index: 1; /* 抬到专注暗角(.focus-shade z:0)与背景光(z:-1)之上 */
   height: 100vh;
   transform: translateZ(0);
   transition: background 0.5s cubic-bezier(0.32, 0.72, 0, 1);
@@ -337,7 +394,9 @@ body.theme-transition *::after {
 }
 
 .sidebar-header {
-  display: block;
+  display: flex;
+  align-items: center;
+  gap: 9px;
   padding: 18px 18px 12px;
   font-size: 13px;
   font-weight: 700;
@@ -348,11 +407,33 @@ body.theme-transition *::after {
   color: inherit;
   text-decoration: none;
   cursor: pointer;
-  transition: opacity 0.2s var(--ease-out), letter-spacing 0.25s var(--ease-out);
+  transition: opacity 0.2s var(--ease-out);
 }
-.sidebar-header:hover {
-  opacity: 0.72;
-  letter-spacing: 0.11em;
+/* logo 单色跟随当前主题文字色，不引入额外颜色 */
+.sidebar-logo {
+  width: 20px;
+  height: 20px;
+  flex: none;
+  display: inline-flex;
+  transition: transform 0.18s var(--ease-out);
+}
+.sidebar-logo svg { width: 100%; height: 100%; display: block; }
+.sidebar-title { transition: letter-spacing 0.25s var(--ease-out); }
+.sidebar-header:hover { opacity: 0.85; }
+.sidebar-header:hover .sidebar-title { letter-spacing: 0.11em; }
+/* hover 时循环环顺时针转一圈并轻微放大，点题 ReadLoops；
+   用 animation（而非 transition）避免鼠标离开时整圈倒转 */
+.sidebar-header:hover .sidebar-logo svg {
+  animation: logoCycle 0.85s var(--ease-damped) forwards;
+}
+.sidebar-header:active .sidebar-logo { transform: scale(0.86); }
+@keyframes logoCycle {
+  0%   { transform: rotate(0deg) scale(1); }
+  70%  { transform: rotate(310deg) scale(1.14); }
+  100% { transform: rotate(360deg) scale(1.06); }
+}
+@media (prefers-reduced-motion: reduce) {
+  .sidebar-header:hover .sidebar-logo svg { animation: none; }
 }
 .sidebar-nav { padding: 8px 10px; flex: 1; overflow-y: auto; }
 .nav-section {
@@ -720,6 +801,23 @@ body.theme-transition *::after {
 /* 句子翻译模式：整句不该进生词本，隐藏该按钮 */
 .lookup-panel.sentence-mode #lpAdd { display: none; }
 .lookup-panel.sentence-mode { max-width: 380px; }
+/* 整句翻译失败的提示与重试 */
+.lookup-panel .translate-hint { font-size: 12px; color: var(--text-tertiary); margin-bottom: 8px; }
+.lookup-panel .translate-retry-btn {
+  height: var(--btn-h-sm);
+  padding: var(--btn-pad-sm);
+  border-radius: var(--btn-radius);
+  border: 1px solid var(--glass-border-strong);
+  background: var(--glass);
+  color: var(--text-secondary);
+  cursor: pointer;
+  font-size: 11px;
+  font-weight: 500;
+  font-family: var(--mono);
+  transition: background 0.2s var(--ease-out), color 0.2s var(--ease-out), transform 0.18s var(--ease-spring);
+}
+.lookup-panel .translate-retry-btn:hover { background: var(--glass-strong); color: var(--text); transform: translateY(-1px); }
+.lookup-panel .translate-retry-btn:active { transform: scale(0.97); }
 .lookup-panel .action-btn {
   height: var(--btn-h-sm);
   padding: var(--btn-pad-sm);
@@ -1862,6 +1960,54 @@ body.theme-transition *::after {
 .right-panel.show {
   transform: translateX(0);
 }
+/* 新手引导箭头：指向右侧抽屉的浮动小玻璃圆钮，触发抽屉后由 JS 加 .dismiss 淡出 */
+.right-guide-arrow {
+  position: fixed;
+  right: 18px;
+  top: 50%;
+  margin-top: -19px; /* 高 38 的一半：垂直居中；transform 留给显隐/退场动画 */
+  width: 38px;
+  height: 38px;
+  z-index: 55; /* 在右边缘触发带(50)之上、抽屉面板(60)之下 */
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 50%;
+  background: var(--glass-strong);
+  backdrop-filter: var(--glass-liquid-strong);
+  -webkit-backdrop-filter: var(--glass-liquid-strong);
+  border: 1px solid var(--glass-border-strong);
+  box-shadow: var(--glass-inner-shadow), 0 6px 20px rgba(0,0,0,0.25);
+  color: var(--text);
+  opacity: 0;
+  transform: translateX(10px) scale(0.9);
+  transition: opacity 0.4s var(--ease-out), transform 0.45s var(--ease-damped);
+  pointer-events: none;
+}
+.right-guide-arrow svg { width: 20px; height: 20px; }
+.right-guide-arrow.show {
+  opacity: 1;
+  transform: translateX(0) scale(1);
+}
+/* 箭头本体持续向右轻推，提示「右边有东西」；显隐交给外层 transform，互不打架 */
+.right-guide-arrow.show svg {
+  animation: guideNudge 2.2s ease-in-out infinite;
+}
+.right-guide-arrow.dismiss {
+  opacity: 0;
+  transform: translateX(16px) scale(0.8);
+  animation: none;
+}
+.right-guide-arrow.dismiss svg { animation: none; }
+@keyframes guideNudge {
+  0%, 100% { transform: translateX(0); }
+  50%      { transform: translateX(3px); }
+}
+/* 专注模式追求极简，隐藏引导 */
+.app.focus-mode .right-guide-arrow { display: none; }
+@media (prefers-reduced-motion: reduce) {
+  .right-guide-arrow.show svg { animation: none; }
+}
 .right-panel.show .right-panel-header {
   animation: slideInRight 0.4s 0.1s cubic-bezier(0.16, 1, 0.3, 1) both;
 }

readloops-2.3.1/app/web/icon.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" role="img" aria-label="ReadLoops">
+  <rect width="512" height="512" rx="104" fill="#1a1818"/>
+  <defs>
+    <linearGradient id="trail" gradientUnits="userSpaceOnUse" x1="382.9" y1="179.8" x2="299.3" y2="114.5">
+      <stop offset="0%" stop-color="#fdfcfc" stop-opacity="0.32"/>
+      <stop offset="55%" stop-color="#fdfcfc" stop-opacity="0.72"/>
+      <stop offset="100%" stop-color="#fdfcfc" stop-opacity="1"/>
+    </linearGradient>
+  </defs>
+  <path d="M 382.86 179.77 A 148 148 0 1 1 299.27 114.47" fill="none" stroke="url(#trail)" stroke-width="38" stroke-linecap="round"/>
+  <path d="M 331.61 124.35 L 291.96 138.37 L 306.58 90.56 Z" fill="#fdfcfc" stroke-linejoin="round"/>
+</svg>

{readloops-2.3.0 → readloops-2.3.1}/app/web/index.html

@@ -5,12 +5,15 @@
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>ReadLoops</title>
   <link rel="manifest" href="/manifest.json">
-  <meta name="theme-color" content="#1a1a1c">
+  <meta name="theme-color" content="#1a1818">
   <meta name="apple-mobile-web-app-capable" content="yes">
   <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
+  <link rel="icon" href="/favicon.ico" sizes="32x32">
   <link rel="icon" type="image/svg+xml" href="/icon.svg">
-  <link rel="apple-touch-icon" href="/icon.svg">
-  <link rel="stylesheet" href="/static/css/style.css?v=37">
+  <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32.png">
+  <link rel="icon" type="image/png" sizes="16x16" href="/favicon-16.png">
+  <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">
+  <link rel="stylesheet" href="/static/css/style.css?v=42">
 </head>
 <body>
   <!-- 液态玻璃 SVG 滤镜（边缘折射效果） -->
@@ -33,7 +36,10 @@
   </svg>
   <div class="app">
     <aside class="sidebar" id="sidebar">
-      <a class="sidebar-header" id="projectHomeLink" href="https://github.com/pekoqq/ReadLoops" target="_blank" rel="noopener noreferrer" title="在 GitHub 上查看项目">ReadLoops</a>
+      <a class="sidebar-header" id="projectHomeLink" href="https://github.com/pekoqq/ReadLoops" target="_blank" rel="noopener noreferrer" title="在 GitHub 上查看项目">
+        <span class="sidebar-logo" aria-hidden="true"><svg viewBox="0 0 512 512" fill="none"><path d="M 382.86 179.77 A 148 148 0 1 1 299.27 114.47" stroke="currentColor" stroke-width="38" stroke-linecap="round"/><path d="M 331.79 124.41 L 291.96 138.37 L 306.58 90.56 Z" fill="currentColor" stroke-linejoin="round"/></svg></span>
+        <span class="sidebar-title">ReadLoops</span>
+      </a>
       <nav class="sidebar-nav">
         <div class="nav-section">阅读</div>
         <div class="nav-item active" data-view="reader">阅读</div>
@@ -174,6 +180,14 @@
     </div>
   </div>
 
-  <script src="/static/js/app.js?v=37"></script>
+  <!-- 专注聚焦遮罩：四周轻微收暗，把视线收向中央阅读卡（body.focus-mode 时淡入） -->
+  <div class="focus-shade" aria-hidden="true"></div>
+
+  <!-- 新手引导：浮动小玻璃箭头，指向右侧查词记录抽屉，触发一次抽屉后消失 -->
+  <div class="right-guide-arrow" id="rightGuideArrow" aria-hidden="true">
+    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"><path d="M9 6l6 6-6 6"/></svg>
+  </div>
+
+  <script src="/static/js/app.js?v=40"></script>
 </body>
 </html>

{readloops-2.3.0 → readloops-2.3.1}/app/web/js/app.js

@@ -247,10 +247,14 @@ function toggleFocusMode() {
   }
   focusMode = !focusMode;
   document.querySelector('.app').classList.toggle('focus-mode', focusMode);
+  // body 同步切类：驱动氛围光层上移 / 回位（过渡与水纹涟漪对齐）
+  document.body.classList.toggle('focus-mode', focusMode);
   if (focusMode) {
     focusStartTime = Date.now();
     $('#focusBtn').textContent = '退出专注';
     $('#focusBtn').classList.add('active');
+    // 进入专注 = 开始沉浸阅读：有文章且计时未跑时同步开始计时
+    if (currentArticle && !timerRunning) startTimer();
     toast('已进入专注模式');
     // 触发水纹扩散引导
     setTimeout(triggerRipple, 300);
@@ -259,6 +263,10 @@ function toggleFocusMode() {
     focusTotalTime += duration;
     $('#focusBtn').textContent = '专注';
     $('#focusBtn').classList.remove('active');
+    // 退出专注 = 暂停阅读：同步暂停计时（再次进入会从当前读数继续）
+    if (timerRunning) pauseTimer();
+    // 已非专注，计时按钮回到「开始（即进入专注）」语义，而不是「继续」
+    $('#timerBtn').textContent = '开始 [空格]';
     const mins = Math.floor(duration / 60);
     const secs = duration % 60;
     toast(`本次专注 ${mins}分${secs}秒`);
@@ -369,11 +377,6 @@ document.addEventListener('keydown', (e) => {
     toggleFocusMode();
     return;
   }
-  // Space 暂停/继续计时（不在输入框中时）
-  if (e.key === ' ' && !['INPUT','TEXTAREA'].includes(e.target.tagName)) {
-    e.preventDefault();
-    toggleTimer();
-  }
 });
 
 // 计时器
@@ -383,6 +386,8 @@ function formatTime(s) {
   return `${m}:${sec}`;
 }
 function startTimer() {
+  // 计时器与专注模式一体：非专注状态下一律不计时（根防线，任何入口都绕不过）
+  if (!focusMode) return;
   if (timerRunning) return;
   timerRunning = true;
   $('#timerBtn').textContent = '暂停 [空格]';
@@ -396,12 +401,22 @@ function pauseTimer() {
   clearInterval(timerInterval);
   $('#timerBtn').textContent = '继续 [空格]';
 }
-$('#timerBtn').addEventListener('click', () => timerRunning ? pauseTimer() : startTimer());
+// 计时与专注一体：非专注时「开始计时」即进入专注模式；已在专注中则只做暂停 / 继续
+function toggleTimerWithFocus() {
+  if (!focusMode) {
+    const view = document.querySelector('.nav-item.active')?.dataset.view;
+    if (view !== 'reader' || !currentArticle) return; // 非阅读页 / 还没文章：不启动
+    toggleFocusMode(); // 进入专注，其进入分支会负责 startTimer
+  } else {
+    timerRunning ? pauseTimer() : startTimer();
+  }
+}
+$('#timerBtn').addEventListener('click', toggleTimerWithFocus);
 
 document.addEventListener('keydown', (e) => {
   if (e.code === 'Space' && !['INPUT','SELECT','TEXTAREA'].includes(e.target.tagName)) {
     e.preventDefault();
-    timerRunning ? pauseTimer() : startTimer();
+    toggleTimerWithFocus();
   }
   if (e.key === 'Escape') { hideLookupPanel(); closeSettings(); }
 });
@@ -669,7 +684,8 @@ document.addEventListener('mouseup', (e) => {
   if (lookupPanel.contains(e.target)) return;
   const sel = window.getSelection();
   const text = sel.toString().trim();
-  if (!text || text.length > 60 || !/[a-zA-Z]/.test(text)) { hideLookupPanel(); return; }
+  // 上限 280：整句翻译需要容纳 1~2 个完整句子（原 60 稍长一点的句子直接不弹面板）
+  if (!text || text.length > 280 || !/[a-zA-Z]/.test(text)) { hideLookupPanel(); return; }
   if (!$('#reader').contains(sel.anchorNode)) { hideLookupPanel(); return; }
   currentSelection = text;
   showLookupPanel(e.clientX, e.clientY, text);
@@ -682,18 +698,14 @@ async function showLookupPanel(x, y, word) {
   $('#lpWord').textContent = word;
   $('#lpPhonetic').textContent = '';
   $('#lpMeaning').textContent = '查询中...';
-  if (!timerRunning && currentArticle) startTimer();
+  // 计时由「划词自动进入专注」统一带动（mouseup → tryAutoFocus → 进专注即计时），
+  // 这里不再单独 startTimer，避免出现非专注计时
 
   // 选中多个单词 → 翻译整句；单个单词 → 查词典
   if (/\s/.test(word.trim())) {
     lookupPanel.classList.add('sentence-mode');
     lookupPanel.dataset.wordId = '';
-    try {
-      const res = await api.post('/api/words/translate', { text: word });
-      $('#lpMeaning').textContent = res.translation || '翻译失败';
-    } catch (err) {
-      $('#lpMeaning').textContent = '翻译失败';
-    }
+    requestSentenceTranslate(word);
     return;
   }
   lookupPanel.classList.remove('sentence-mode');
@@ -713,6 +725,34 @@ async function showLookupPanel(x, y, word) {
     }
   } catch (err) { $('#lpMeaning').textContent = '查询失败'; }
 }
+// 整句翻译：独立函数，失败时在面板内给出「点击重试」而不是一句死掉的「翻译失败」
+async function requestSentenceTranslate(word) {
+  const meaning = $('#lpMeaning');
+  meaning.textContent = '翻译中...';
+  try {
+    const res = await api.post('/api/words/translate', { text: word });
+    if (res && res.ok && res.translation) {
+      meaning.textContent = res.translation;
+      return;
+    }
+    renderTranslateRetry(word, res && res.error);
+  } catch (err) {
+    renderTranslateRetry(word, String(err));
+  }
+}
+function renderTranslateRetry(word, reason) {
+  if (reason) console.warn('整句翻译失败:', reason);
+  const meaning = $('#lpMeaning');
+  meaning.innerHTML = '';
+  const hint = document.createElement('div');
+  hint.className = 'translate-hint';
+  hint.textContent = '翻译失败（网络或 AI 服务波动）';
+  const btn = document.createElement('button');
+  btn.className = 'translate-retry-btn';
+  btn.textContent = '点击重试';
+  btn.addEventListener('click', () => requestSentenceTranslate(word));
+  meaning.append(hint, btn);
+}
 function hideLookupPanel() { lookupPanel.classList.remove('show'); }
 
 $('#lpPronounce').addEventListener('click', () => {
@@ -954,9 +994,9 @@ $$('.nav-item').forEach(item => {
         <h2>ReadLoops</h2>
         <p>点击「生成文章」开始阅读训练</p>
         <div class="empty-hints">
-          <span><kbd>空格</kbd>开始 / 暂停计时</span>
+          <span><kbd>空格</kbd>开始专注计时 · 暂停继续</span>
           <span><kbd>选中</kbd>查词 · 选整句翻译</span>
-          <span><kbd>F</kbd>专注模式</span>
+          <span><kbd>F</kbd>切换专注模式</span>
         </div>
       </div>`;
         }
@@ -1187,9 +1227,9 @@ async function loadVocab() {
         <h2>ReadLoops</h2>
         <p>点击「生成文章」开始阅读训练</p>
         <div class="empty-hints">
-          <span><kbd>空格</kbd>开始 / 暂停计时</span>
+          <span><kbd>空格</kbd>开始专注计时 · 暂停继续</span>
           <span><kbd>选中</kbd>查词 · 选整句翻译</span>
-          <span><kbd>F</kbd>专注模式</span>
+          <span><kbd>F</kbd>切换专注模式</span>
         </div>
       </div>`;
       }
@@ -1791,6 +1831,19 @@ const rightPanelTrigger = $('#rightPanelTrigger');
 let panelHoverTimer = null;
 let panelPinned = false; // 工具栏按钮打开时固定显示
 
+// 新手引导箭头：没触发过右侧抽屉才显示，首次把抽屉唤出后永久记住（不再打扰）
+const guideArrow = $('#rightGuideArrow');
+const GUIDE_SEEN_KEY = 'readloops_right_guide_seen';
+if (guideArrow && !localStorage.getItem(GUIDE_SEEN_KEY)) {
+  setTimeout(() => guideArrow.classList.add('show'), 900);
+}
+function dismissGuideArrow() {
+  if (!guideArrow || guideArrow.classList.contains('dismiss')) return;
+  guideArrow.classList.remove('show');
+  guideArrow.classList.add('dismiss');
+  localStorage.setItem(GUIDE_SEEN_KEY, '1');
+}
+
 // 鼠标移入右侧边缘触发（带防抖，避免快速划过误触）
 rightPanelTrigger.addEventListener('mouseenter', () => {
   clearTimeout(panelHoverTimer);
@@ -1798,6 +1851,7 @@ rightPanelTrigger.addEventListener('mouseenter', () => {
     if (!panelPinned) {
       rightPanel.classList.add('show');
       loadLookupHistory();
+      dismissGuideArrow(); // 用户已发现右侧抽屉，引导箭头退场
     }
   }, 120);
 });
@@ -1817,6 +1871,7 @@ rightPanel.addEventListener('mouseleave', () => {
 $('#lookupHistoryBtn').addEventListener('click', () => {
   rightPanel.classList.add('show');
   loadLookupHistory();
+  dismissGuideArrow();
 });
 
 async function loadLookupHistory() {

readloops-2.3.1/app/web/manifest.json

@@ -0,0 +1,36 @@
+{
+  "name": "ReadLoops",
+  "short_name": "ReadLoops",
+  "description": "AI 驱动的英语阅读训练器",
+  "start_url": "/",
+  "display": "standalone",
+  "background_color": "#1a1818",
+  "theme_color": "#1a1818",
+  "orientation": "any",
+  "icons": [
+    {
+      "src": "/icon-192.png",
+      "sizes": "192x192",
+      "type": "image/png",
+      "purpose": "any"
+    },
+    {
+      "src": "/icon-512.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "any"
+    },
+    {
+      "src": "/icon-maskable-512.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "maskable"
+    },
+    {
+      "src": "/icon.svg",
+      "sizes": "any",
+      "type": "image/svg+xml",
+      "purpose": "any"
+    }
+  ]
+}

{readloops-2.3.0 → readloops-2.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "readloops"
-version = "2.3.0"
+version = "2.3.1"
 description = "AI 驱动的英语阅读训练器：可理解输入 + FSRS 间隔重复"
 readme = "README.md"
 requires-python = ">=3.10"

{readloops-2.3.0 → readloops-2.3.1}/readloops.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: readloops
-Version: 2.3.0
+Version: 2.3.1
 Summary: AI 驱动的英语阅读训练器：可理解输入 + FSRS 间隔重复
 Author: Fangyuan2711
 License: MIT
@@ -38,9 +38,22 @@ Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
 Requires-Dist: pre-commit>=3.7; extra == "dev"
 Dynamic: license-file
 
-# ReadLoops
+<p align="center">
+  <img src="https://raw.githubusercontent.com/pekoqq/ReadLoops/main/assets/logo.png" width="104" alt="ReadLoops logo">
+</p>
 
-> AI 驱动的英语阅读训练器。基于「可理解输入（i+1）」+ 阅读驱动的 FSRS 间隔重复，面向大学英语四级（进阶六级）。
+<h1 align="center">ReadLoops</h1>
+
+<p align="center">
+  <a href="https://pypi.org/project/readloops/"><img alt="PyPI" src="https://img.shields.io/pypi/v/readloops"></a>
+  <a href="https://pypi.org/project/readloops/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/readloops"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green"></a>
+  <a href="https://github.com/pekoqq/ReadLoops/releases"><img alt="Release" src="https://img.shields.io/github/v/release/pekoqq/ReadLoops"></a>
+</p>
+
+<p align="center">
+  AI 驱动的英语阅读训练器。基于「可理解输入（i+1）」+ 阅读驱动的 FSRS 间隔重复，面向大学英语四级（进阶六级）。
+</p>
 
 ## 它解决什么问题
 

{readloops-2.3.0 → readloops-2.3.1}/readloops.egg-info/SOURCES.txt

@@ -19,6 +19,13 @@ app/services/dict_import.py
 app/services/similarity.py
 app/services/smart_test.py
 app/services/srs.py
+app/web/apple-touch-icon.png
+app/web/favicon-16.png
+app/web/favicon-32.png
+app/web/favicon.ico
+app/web/icon-192.png
+app/web/icon-512.png
+app/web/icon-maskable-512.png
 app/web/icon.svg
 app/web/index.html
 app/web/manifest.json

readloops-2.3.0/app/web/icon.svg

@@ -1,14 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
-  <defs>
-    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
-      <stop offset="0%" style="stop-color:#2d2d30"/>
-      <stop offset="100%" style="stop-color:#1a1a1c"/>
-    </linearGradient>
-  </defs>
-  <rect width="512" height="512" rx="96" fill="url(#bg)"/>
-  <g transform="translate(256, 256)">
-    <path d="M -90 -60 A 110 110 0 1 1 -90 60" fill="none" stroke="white" stroke-width="22" stroke-linecap="round" opacity="0.9"/>
-    <polygon points="-90,80 -60,55 -120,55" fill="white" opacity="0.9"/>
-    <path d="M 30 -30 L 30 30 M 30 30 L 70 0" fill="none" stroke="white" stroke-width="16" stroke-linecap="round" stroke-linejoin="round" opacity="0.7"/>
-  </g>
-</svg>

readloops-2.3.0/app/web/manifest.json

@@ -1,24 +0,0 @@
-{
-  "name": "ReadLoops",
-  "short_name": "ReadLoops",
-  "description": "AI 驱动的英语阅读训练器",
-  "start_url": "/",
-  "display": "standalone",
-  "background_color": "#1a1a1c",
-  "theme_color": "#1a1a1c",
-  "orientation": "any",
-  "icons": [
-    {
-      "src": "/icon.svg",
-      "sizes": "any",
-      "type": "image/svg+xml",
-      "purpose": "any"
-    },
-    {
-      "src": "/icon.svg",
-      "sizes": "any",
-      "type": "image/svg+xml",
-      "purpose": "maskable"
-    }
-  ]
-}