papersearch 0.4.0 → 0.4.3

package/carsi/paper_search_carsi/engine/bridge.py

@@ -36,6 +36,7 @@ _FAILURE_KINDS = {
     "publisher_content_error": ("publisher_content_error", "review_publisher_error"),
     "unsupported_platform": ("unsupported_platform", "review_publisher_error"),
     "browser_unresponsive": ("browser_unresponsive", "review_browser"),
+    "browser_operation_timeout": ("browser_operation_timeout", "review_browser"),
     "publisher_access_blocked": ("access_blocked", "review_access"),
     "publisher_unreachable": ("publisher_unreachable", "review_publisher_error"),
     "sso_required": ("paywall", "login_required"),
@@ -45,6 +46,7 @@ _FAILURE_KINDS = {
     "unexpected_error": ("source_exception", ""),
     "user_marked_no_entitlement": ("no_entitlement", "skipped_by_user"),
     "user_skipped": ("user_skipped", "skipped_by_user"),
+    "batch_stopped": ("batch_stopped", "stopped_by_user"),
     "pdf_wrong_article": ("pdf_wrong_article", "review_browser"),
     "supplements_only": ("supplements_only", "supplements_only"),
     # The DOI resolves to no site to sign in on (publishers/site.py): no driver can run.
@@ -508,7 +510,8 @@ def _try_browser_batch_download(
         require_interactive_browser=True,
     )
 
-    run_dir = output_path.parent / ".browser_runs"
+    from uuid import uuid4
+    run_dir = Path(config.get("diagnostics_dir") or output_path.parent / "diagnostics") / uuid4().hex[:12]
     run_dir.mkdir(parents=True, exist_ok=True)
 
     log.info(f"   [Institutional] Browser batch download: {doi} via {profile.name}")
@@ -536,10 +539,10 @@ def _try_browser_batch_download(
             if watchdog.fired and not result.ok:
                 # The browser call never returned and the driver was stopped:
                 # whatever the engine reported after that is a consequence.
-                result.reason = result.state = "browser_unresponsive"
+                result.reason = result.state = watchdog.failure_code()
             if supplements_mode in ("with", "only"):
-                if result.state == "browser_unresponsive":
-                    result.supplements = [{"status": "skipped", "reason": "browser_unresponsive",
+                if result.state in ("browser_unresponsive", "browser_operation_timeout"):
+                    result.supplements = [{"status": "skipped", "reason": result.state,
                                            "url": "", "label": ""}]
                 elif result.state == "challenge_or_viewer_timeout":
                     # The verification page was never completed: the article
@@ -547,13 +550,16 @@ def _try_browser_batch_download(
                     result.supplements = [{"status": "skipped", "reason": "challenge_timeout",
                                            "url": "", "label": ""}]
                 elif result.state in ("unsupported_platform", "publisher_access_blocked", "publisher_unreachable",
-                                      "login_page_closed"):
+                                      "login_page_closed", "user_skipped", "batch_stopped",
+                                      "user_marked_no_entitlement"):
                     # Nothing more to fetch there now.
                     result.supplements = [{"status": "skipped", "reason": result.state,
                                            "url": "", "label": ""}]
                 else:
                     written = len(result.events)
-                    result.supplements = downloader.collect_supplements(context, doi, output_path.parent, result)
+                    result.supplements = downloader.collect_supplements(context, doi, output_path.parent, result, manifest_dir=run_dir)
+                    if supplements_mode == "only" and (run_dir / "manifest.json").is_file():
+                        result.record_path = str(run_dir / "manifest.json")
                     _note_supplements(result, written)
         finally:
             try:
@@ -576,6 +582,8 @@ def _try_browser_batch_download(
                 if output_path.exists():
                     output_path.unlink()
                 src.rename(output_path)
+            result.pdf_path = str(output_path)
+            _note_supplements(result, len(getattr(result, "events", [])))
             log.info(f"   [Institutional] Browser download succeeded: {result.size_bytes:,} bytes")
             return {
                 "success": True, "identifier": doi, "doi": doi,
@@ -617,8 +625,9 @@ def _note_supplements(result: Any, written: int) -> None:
         if not path.is_file():
             continue
         data = json.loads(path.read_text(encoding="utf-8"))
-        data["events"] = list(data.get("events") or []) + list(result.events[written:])
-        data["supplements"] = result.supplements
+        data["events"] = list(data.get("events") or []) + list(getattr(result, "events", [])[written:])
+        data["supplements"] = getattr(result, "supplements", [])
+        data["pdf_path"] = str(getattr(result, "pdf_path", "") or "")
         if getattr(result, "phases", None):
             data["phases"] = {k: round(float(v), 1) for k, v in result.phases.items()}
         path.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")

package/carsi/paper_search_carsi/engine/supplements.py

@@ -21,6 +21,8 @@ from typing import Any, Callable, Iterable
 from urllib.parse import unquote, urlparse
 
 from ..adapters.base import SupplementLink
+from ..browser.watchdog import BrowserUnresponsive, BrowserOperationTimeout
+from ..entitlements import UserMarkedNoEntitlement, UserSkippedArticle, UserStoppedBatch
 
 MAX_FILES = 50
 MAX_FILE_BYTES = 200 * 1024 * 1024
@@ -87,26 +89,35 @@ def _get(request: Any, url: str, entry: dict[str, Any], sleep) -> Any:
 
 def collect(request: Any, links: Iterable[SupplementLink], output_dir: Path, doi: str, *,
             clock=time.monotonic, sleep=time.sleep,
-            download: Callable[[str], tuple[bytes, str]] | None = None) -> list[dict[str, Any]]:
+            manifest_dir: Path | None = None,
+            target_dir: Path | None = None,
+            download: Callable[[str], tuple[bytes, str]] | None = None,
+            progress: Callable[[int], None] | None = None) -> list[dict[str, Any]]:
     """Fetch ``links`` with ``request`` (a Playwright APIRequestContext). A file
     refused with 403 is taken through ``download`` when given: the browser
     opens it and downloads it itself (Taylor & Francis behind Cloudflare
     refused every scripted request with ego, the page's own fetch included,
-    and let the browser's own navigation through, 2026-11-01)."""
+    and let the browser's own navigation through, 2026-11-01). ``progress`` is
+    told how many files are saved after each one (the progress window)."""
     unique: list[SupplementLink] = []
     for link in links:
         if link.url and link.url not in {u.url for u in unique}:
             unique.append(link)
     if not unique:
         return []
-    target = supplements_dir(output_dir, doi)
+    target = target_dir or supplements_dir(output_dir, doi)
     target.mkdir(parents=True, exist_ok=True)
     started = clock()
     taken: set[str] = set()
     files: list[dict[str, Any]] = []
+    stopped_reason = ""
     for index, link in enumerate(unique):
         entry: dict[str, Any] = {"url": link.url, "label": link.label}
-        if index >= MAX_FILES:
+        if stopped_reason:
+            entry.update(status="skipped", reason=stopped_reason)
+        elif link.error:
+            entry.update(status="failed", reason=link.error)
+        elif index >= MAX_FILES:
             entry.update(status="skipped", reason="file_limit")
         elif clock() - started > TIME_BUDGET_SEC:
             entry.update(status="skipped", reason="time_budget")
@@ -136,9 +147,21 @@ def collect(request: Any, links: Iterable[SupplementLink], output_dir: Path, doi
                         path.write_bytes(body)
                         entry.update(status="saved", file=str(path), size=len(body),
                                      content_type=content_type.split(";")[0].strip())
+            except (BrowserUnresponsive, UserMarkedNoEntitlement) as exc:
+                stopped_reason = ("batch_stopped" if isinstance(exc, UserStoppedBatch) else
+                                  "user_skipped" if isinstance(exc, UserSkippedArticle) else
+                                  "user_marked_no_entitlement" if isinstance(exc, UserMarkedNoEntitlement) else
+                                  "browser_operation_timeout" if isinstance(exc, BrowserOperationTimeout) else
+                                  "browser_unresponsive")
+                entry.update(status="skipped" if isinstance(exc, UserMarkedNoEntitlement) else "failed",
+                             reason=stopped_reason)
             except Exception as exc:
                 entry.update(status="failed", reason=f"{type(exc).__name__}: {str(exc)[:160]}")
         files.append(entry)
-    (target / "manifest.json").write_text(
+        if progress is not None:
+            progress(sum(1 for f in files if f.get("status") == "saved"))
+    manifest_target = manifest_dir or target
+    manifest_target.mkdir(parents=True, exist_ok=True)
+    (manifest_target / "manifest.json").write_text(
         json.dumps({"doi": doi, "files": files}, ensure_ascii=False, indent=2), encoding="utf-8")
     return files

package/carsi/paper_search_carsi/entitlements.py

@@ -34,6 +34,14 @@ class UserSkippedArticle(UserMarkedNoEntitlement):
     """The user pressed "skip this paper": it ends, nothing is remembered."""
 
 
+class UserStoppedBatch(UserMarkedNoEntitlement):
+    """The user pressed "stop the task": this paper ends and the batch stops."""
+
+
+# Not an entitlement decision: nothing is recorded, the batch ends.
+STOP_BATCH = "stop_batch"
+
+
 SKIP = "skip"
 ALLOW = "allow"
 _ACTIONS = {
@@ -183,7 +191,7 @@ def clear(key: str) -> bool:
 
 def request_action(current: str, action: str, run_id: str = "") -> None:
     """Written by the progress window when the user presses a button."""
-    if action not in _ACTIONS:
+    if action not in _ACTIONS and action != STOP_BATCH:
         raise ValueError("unknown action")
     _write_json(control_path(), {"current": current, "action": action, "run_id": run_id, "at": time.time()})
 
@@ -204,7 +212,7 @@ def take_action(doi: str, since: float) -> str | None:
     except OSError:
         pass
     action = data.get("action")
-    return action if action in _ACTIONS else None
+    return action if action in _ACTIONS or action == STOP_BATCH else None
 
 
 def apply_user_decision(doi: str, publisher: str, since: float) -> str | None:
@@ -212,6 +220,8 @@ def apply_user_decision(doi: str, publisher: str, since: float) -> str | None:
     action = take_action(doi, since)
     if not action:
         return None
+    if action == STOP_BATCH:
+        raise UserStoppedBatch(action)
     if action == "skip_item":
         raise UserSkippedArticle(action)
     try:

package/carsi/paper_search_carsi/log.py

@@ -29,9 +29,8 @@ def _file_handler() -> logging.Handler | None:
 
 
 def enable_stack_dump() -> None:
-    """``kill -USR1 <pid>`` appends every thread's Python stack to
-    ``<data dir>/logs/stacks-<date>.txt``: a backend waiting forever on a browser
-    call (Camoufox, 2026-10-31) shows where it waits."""
+    """Prepare watchdog dumps on every OS; POSIX also supports ``kill -USR1``.
+    Stacks go to ``<data dir>/logs/stacks-<date>.txt``."""
     global _stack_file
     import faulthandler
     import os
@@ -39,15 +38,22 @@ def enable_stack_dump() -> None:
     from datetime import date
     from pathlib import Path
 
-    if _stack_file is not None or not hasattr(signal, "SIGUSR1") or os.environ.get("CARSI_FILE_LOG") == "0":
+    if _stack_file is not None or os.environ.get("CARSI_FILE_LOG") == "0":
         return
     try:
         log_dir = Path(os.environ.get("CARSI_DATA_DIR", str(Path.home() / ".local" / "share" / "paper-search-cli" / "carsi"))) / "logs"
         log_dir.mkdir(parents=True, exist_ok=True)
         _stack_file = open(log_dir / f"stacks-{date.today().isoformat()}.txt", "a", encoding="utf-8")
-        faulthandler.register(signal.SIGUSR1, file=_stack_file, all_threads=True)
-    except Exception:
-        _stack_file = None
+    except OSError:
+        get_logger().warning("Could not open the browser watchdog stack log")
+        return
+    # Windows has no SIGUSR1/register, but dump_traceback works there. A failed
+    # optional signal hook must not disable explicit watchdog dumps either.
+    if hasattr(signal, "SIGUSR1"):
+        try:
+            faulthandler.register(signal.SIGUSR1, file=_stack_file, all_threads=True)
+        except (OSError, RuntimeError, ValueError):
+            get_logger().warning("Stack log ready, but the SIGUSR1 hook is unavailable")
 
 
 def dump_stacks(reason: str) -> bool:

package/carsi/paper_search_carsi/orchestrator.py

@@ -32,6 +32,7 @@ def download_institutional(
     strategy: str | None = None,
     supplements: str | None = None,
     user_wait: str | None = None,
+    diagnostics_dir: str | None = None,
 ) -> dict[str, Any]:
     """Download one DOI through institutional access only.
 
@@ -66,6 +67,8 @@ def download_institutional(
         extra = {"supplements": supplements} if supplements in ("with", "only") else {}
         if user_wait == "short":
             extra["user_wait"] = user_wait
+        if diagnostics_dir:
+            extra["diagnostics_dir"] = diagnostics_dir
         return _download_impl(doi, output_dir, **extra)
     finally:
         with _INFLIGHT_LOCK:
@@ -73,7 +76,8 @@ def download_institutional(
 
 
 def _download_impl(doi: str, output_dir: str | Path | None, *,
-                   supplements: str | None = None, user_wait: str | None = None) -> dict[str, Any]:
+                   supplements: str | None = None, user_wait: str | None = None,
+                   diagnostics_dir: str | None = None) -> dict[str, Any]:
     config = load_config()
     if user_wait == "short":
         config["user_wait"] = "short"
@@ -82,6 +86,8 @@ def _download_impl(doi: str, output_dir: str | Path | None, *,
 
     target_dir = Path(output_dir) if output_dir else Path(config["output_dir"])
     target_dir.mkdir(parents=True, exist_ok=True)
+    if diagnostics_dir:
+        config["diagnostics_dir"] = str(Path(diagnostics_dir).resolve())
     output_path = target_dir / f"{safe_filename(doi)}.pdf"
 
     cached = cache_get(doi, config)

package/carsi/paper_search_carsi/progress_bar.py

@@ -29,6 +29,7 @@ from typing import Any
 import os as _os
 import sys as _sys
 
+from . import user_settings
 from .progress_reporter import read_state
 
 # --- Win32 / DWM constants -------------------------------------------------
@@ -43,6 +44,13 @@ DWMSBT_MAINWINDOW = 2  # light Mica
 
 # Palettes: (light, dark). Picked once at start from the OS appearance.
 CONTENT_LABELS = {"main": "正文", "supplements": "附录", "both": "正文+附录"}
+# The step of the main text, as the status line says it ("正文 · 正在获取 PDF").
+STAGE_TEXT = {
+    "starting": "准备中", "opening_article": "正在打开文章", "checking_access": "正在检查访问权限",
+    "waiting_login": "等待机构登录", "waiting_verification": "等待人机验证", "fetching_pdf": "正在获取 PDF",
+    "pdf_captured": "已读到 PDF，正在核对", "saved_pending_verification": "已保存",
+    "route_failed": "这条路没走通，正在换路",
+}
 
 PALETTES = {
     "light": {
@@ -227,11 +235,14 @@ class ProgressWindow:
         self._apply_backdrop()
         self._fonts()
         self._bind_mouse()
+        self._draw_bindings: list[tuple[str, str, str]] = []
         self._finished_elapsed: float | None = None
         self._finished_run: object = None
         self._flash: tuple[str, float, str] | None = None  # (text, until, doi)
         self._chosen: tuple[str, str] | None = None  # (doi, action) pressed for the current paper
         self._hover = ""  # the button under the mouse; kept across redraws
+        self._settings: tk.Toplevel | None = None  # the settings dialog, when open
+        self._last_current = ""  # the paper shown, for a message after the dialog closes
         self.root.after(400, self._tick)
 
     # --- window plumbing ---------------------------------------------------
@@ -351,6 +362,21 @@ class ProgressWindow:
             return _fmt_elapsed((end - started).total_seconds())
         return _fmt_elapsed((datetime.now() - started).total_seconds())
 
+    @staticmethod
+    def _status_text(state: dict[str, Any], running: bool) -> str:
+        """The status line: which part of the paper is being fetched and how far,
+        "正文 · 正在获取 PDF" or "附录 · 已保存 2/5"; between papers, the phase."""
+        phase = str(state.get("phase") or ("处理中" if running else ""))
+        part = str(state.get("part") or "")
+        if not running or state.get("awaiting_next") or part not in ("main", "supplements"):
+            return phase
+        if part == "supplements":
+            total = state.get("supplements_total")
+            if not isinstance(total, int):
+                return "附录 · 正在查找附录文件"
+            return f"附录 · 已保存 {int(state.get('supplements_saved') or 0)}/{total}"
+        return "正文 · " + STAGE_TEXT.get(str(state.get("stage") or ""), phase)
+
     @staticmethod
     def _attention_items(state: dict[str, Any]) -> list[dict[str, Any]]:
         attention = state.get("attention")
@@ -362,15 +388,27 @@ class ProgressWindow:
             return [v for v in attention if isinstance(v, dict)]
         return []
 
+    def _bind_draw(self, tag: str, event: str, callback: Any) -> None:
+        """A binding owned by this frame, released before its items are deleted."""
+        command = self.canvas.tag_bind(tag, event, callback)
+        self._draw_bindings.append((tag, event, command))
+
     def _draw(self, state: dict[str, Any] | None) -> None:
         c, col, s = self.canvas, self.c, self.s
+        # Canvas.delete removes items, not tag_bind's registered Tcl/Python
+        # commands. Keep neither old state nor callbacks across the 500 ms redraws.
+        for tag, event, command in self._draw_bindings:
+            c.tag_unbind(tag, event, command)
+        self._draw_bindings.clear()
         c.delete("all")
         P = self.P
         Wl = max(self.W, c.winfo_width())
         Hl = max(self.H, c.winfo_height())
         u = lambda n: int(round(n * s))
 
+        gear_left = self._draw_gear(Wl - P, P + u(9))
         if not state:
+            self._last_current = ""
             c.create_text(Wl // 2, Hl // 2 - u(8), text="PaperSearch", fill=col["text"], font=self.f_title)
             c.create_text(Wl // 2, Hl // 2 + u(14), text="暂无下载任务", fill=col["dim"], font=self.f_small)
             return
@@ -401,8 +439,8 @@ class ProgressWindow:
         dot = u(8)
         c.create_oval(P, y1 - dot // 2, P + dot, y1 + dot // 2, fill=tone, outline=tone)
         count = f"{done} / {total}" if total else f"{done}"
-        c.create_text(Wl - P, y1, text=count, fill=col["text"], font=self.f_count, anchor="e")
-        count_w = self.f_count.measure(count)
+        c.create_text(gear_left - u(8), y1, text=count, fill=col["text"], font=self.f_count, anchor="e")
+        count_w = self.f_count.measure(count) + (Wl - P - gear_left) + u(8)
         # What this download fetches, as a small label left of the count.
         content = CONTENT_LABELS.get(str(state.get("content") or "main"), CONTENT_LABELS["main"])
         chip_h = u(18)
@@ -440,13 +478,14 @@ class ProgressWindow:
             self._pill(P - u(2), y2 - u(11), P + self.f_body.measure(text) + u(14), y2 + u(11), col["warn_bg"])
             c.create_text(P + u(6), y2, text=text, fill=col["warn"], font=self.f_body, anchor="w")
         else:
-            phase = str(state.get("phase") or ("处理中" if running else ""))
+            phase = self._status_text(state, running)
             c.create_text(P, y2, anchor="w", fill=col["dim"], font=self.f_body,
                           text=_elide(self.f_body, phase, phase_room))
 
         # Row 3: the paper being worked on
         y3 = y2 + u(22)
         current = str((attention[-1].get("current") if attention else "") or state.get("current") or "")
+        self._last_current = current
         if current:
             c.create_text(P, y3, anchor="w", fill=col["text"] if running else col["dim"], font=self.f_mono,
                           text=_elide(self.f_mono, current, Wl - 2 * P))
@@ -484,7 +523,7 @@ class ProgressWindow:
             x = P
             chosen = self._chosen[1] if self._chosen and self._chosen[0] == current else ""
             for key, label in (("skip_item", "跳过本篇"), ("skip_journal", "本刊无权限"),
-                               ("skip_publisher", "出版社无权限")):
+                               ("skip_publisher", "出版社无权限"), ("stop_batch", "终止任务")):
                 pressed = key == chosen
                 text = ("✓ " + label) if pressed else label
                 w = self.f_small.measure(text) + u(18)
@@ -492,23 +531,24 @@ class ProgressWindow:
                 self._pill(x, y6 - u(11), x + w, y6 + u(11), col["warn"] if pressed else col["track"], tags=(tag,))
                 fill = col["bg"] if pressed else (col["text"] if self._hover == key else col["btn"])
                 label_id = c.create_text(x + w / 2, y6, text=text, fill=fill, font=self.f_small, tags=(tag,))
-                c.tag_bind(tag, "<Button-1>", lambda e, k=key, d=current, s=state: self._decide(k, d, s))
+                self._bind_draw(tag, "<Button-1>", lambda e, k=key, d=current, s=state: (
+                    self._stop(d, s) if k == "stop_batch" else self._decide(k, d, s)))
                 if not pressed:
-                    c.tag_bind(tag, "<Enter>", lambda e, k=key, i=label_id: self._hover_button(k, i))
-                    c.tag_bind(tag, "<Leave>", lambda e, i=label_id: self._hover_button("", i))
+                    self._bind_draw(tag, "<Enter>", lambda e, k=key, i=label_id: self._hover_button(k, i))
+                    self._bind_draw(tag, "<Leave>", lambda e, i=label_id: self._hover_button("", i))
                 x += w + u(8)
             # Problem report for the agent to review: a small flag icon, right-aligned.
             c.create_text(Wl - P, y6, text="\u2691", fill=col["faint"], font=self.f_body,
                           anchor="e", tags=("report",))
-            c.tag_bind("report", "<Button-1>", lambda e, d=current, s=state: self._report_menu(e, d, s))
+            self._bind_draw("report", "<Button-1>", lambda e, d=current, s=state: self._report_menu(e, d, s))
 
         output_dir = str(state.get("output_dir") or "")
         if output_dir:
             link = c.create_text(Wl - P, y5, text="打开文件夹", fill=col["link"], font=self.f_small,
                                  anchor="e", tags=("outdir",))
-            c.tag_bind("outdir", "<Button-1>", lambda e: self._open_output_dir(state))
-            c.tag_bind("outdir", "<Enter>", lambda e: c.itemconfigure(link, font=self._underlined()))
-            c.tag_bind("outdir", "<Leave>", lambda e: c.itemconfigure(link, font=self.f_small))
+            self._bind_draw("outdir", "<Button-1>", lambda e: self._open_output_dir(state))
+            self._bind_draw("outdir", "<Enter>", lambda e: c.itemconfigure(link, font=self._underlined()))
+            self._bind_draw("outdir", "<Leave>", lambda e: c.itemconfigure(link, font=self.f_small))
 
     def _decide(self, action: str, doi: str, state: dict[str, Any]) -> None:
         """Ask the running download to apply the user's entitlement decision."""
@@ -516,7 +556,8 @@ class ProgressWindow:
             from .entitlements import request_action
 
             request_action(doi, action, str(state.get("run_id") or ""))
-            text = {"skip_item": "已跳过本篇，进入下一篇",
+            text = {"stop_batch": "已终止任务：这一篇结束，剩下的不再下载",
+                    "skip_item": "已跳过本篇，进入下一篇",
                     "skip_journal": "已记住：本刊无权限，以后自动跳过（可用 entitlements 撤销）",
                     "skip_publisher": "已记住：该出版社无权限，以后自动跳过"}[action]
         except Exception as exc:
@@ -525,6 +566,109 @@ class ProgressWindow:
         self._chosen = (doi, action)
         self._draw(state)
 
+    def _stop(self, doi: str, state: dict[str, Any]) -> None:
+        """Stop the whole task, after asking: this paper ends, the rest are not downloaded."""
+        from tkinter import messagebox
+
+        left = max(0, int(state.get("total", 0) or 0) - int(state.get("done", 0) or 0) - 1)
+        question = "终止整个下载任务？这一篇立即结束" + (f"，剩下的 {left} 篇不再下载。" if left else "。")
+        if messagebox.askyesno("终止任务", question, parent=self.root):
+            self._decide("stop_batch", doi, state)
+
+    def _draw_gear(self, right: int, y: int) -> int:
+        """Round settings button with a small, font-independent gear."""
+        import math
+
+        c, col, s = self.canvas, self.c, self.s
+        d = 17.6 * s
+        x0, cx = right - d, right - d / 2
+        c.create_oval(x0, y - d / 2, right, y + d / 2,
+                      fill=col["track"], outline=col["track"], tags=("settings",))
+        # 11.2 px = 70% of the previous 16 px icon. Angular teeth keep the
+        # original gear appearance without platform-specific font rendering.
+        points = []
+        for tooth in range(8):
+            for offset, radius in ((-0.5, 4.1), (-0.28, 5.6), (0.28, 5.6), (0.5, 4.1)):
+                angle = (tooth + offset) * math.pi / 4
+                points.extend((cx + radius * s * math.cos(angle), y + radius * s * math.sin(angle)))
+        gear = c.create_polygon(*points, fill=col["btn"], outline="", tags=("settings",))
+        r = 2.1 * s
+        c.create_oval(cx - r, y - r, cx + r, y + r, fill=col["track"], outline="", tags=("settings",))
+        self._bind_draw("settings", "<Button-1>", lambda e: self._open_settings())
+        self._bind_draw("settings", "<Enter>", lambda e: c.itemconfigure(gear, fill=col["text"]))
+        self._bind_draw("settings", "<Leave>", lambda e: c.itemconfigure(gear, fill=col["btn"]))
+        return x0
+
+    def _open_settings(self) -> None:
+        """The settings dialog: each value typed in and checked; saved values
+        apply from the next paper."""
+        if self._settings is not None and self._settings.winfo_exists():
+            self._settings.lift()
+            return
+        col, pad = self.c, int(round(14 * self.s))
+        top = self._settings = tk.Toplevel(self.root, bg=col["bg"])
+        top.title("设置")
+        top.resizable(False, False)
+        top.attributes("-topmost", True)
+        top.transient(self.root)
+        frame = tk.Frame(top, bg=col["bg"], padx=pad, pady=pad)
+        frame.pack(fill="both", expand=True)
+        tk.Label(frame, text="设置", bg=col["bg"], fg=col["text"], font=self.f_title).grid(
+            row=0, column=0, columnspan=3, sticky="w", pady=(0, pad // 2))
+        values = user_settings.current()
+        entries: dict[str, tk.Entry] = {}
+        errors: dict[str, tk.Label] = {}
+        for i, field in enumerate(user_settings.FIELDS):
+            row = 1 + 2 * i
+            tk.Label(frame, text=field.label, bg=col["bg"], fg=col["text"], font=self.f_body).grid(
+                row=row, column=0, sticky="w", padx=(0, pad))
+            entry = tk.Entry(frame, width=6, justify="right", font=self.f_body)
+            entry.insert(0, str(values[field.name]))
+            entry.grid(row=row, column=1, pady=3)
+            tk.Label(frame, text=field.unit, bg=col["bg"], fg=col["dim"], font=self.f_body).grid(
+                row=row, column=2, sticky="w", padx=(6, 0))
+            error = tk.Label(frame, text="", bg=col["bg"], fg=col["bad"], font=self.f_small)
+            error.grid(row=row + 1, column=0, columnspan=3, sticky="w")
+            error.grid_remove()
+            entries[field.name], errors[field.name] = entry, error
+
+        def reset() -> None:
+            for field in user_settings.FIELDS:
+                entries[field.name].delete(0, "end")
+                entries[field.name].insert(0, str(field.default))
+                errors[field.name].grid_remove()
+
+        def save() -> None:
+            chosen: dict[str, int] = {}
+            for field in user_settings.FIELDS:
+                value, problem = user_settings.check(field, entries[field.name].get())
+                if problem:
+                    errors[field.name].configure(text=problem)
+                    errors[field.name].grid()
+                else:
+                    errors[field.name].grid_remove()
+                    chosen[field.name] = int(value)
+            if len(chosen) < len(user_settings.FIELDS):
+                return
+            try:
+                user_settings.save(chosen)
+                text = "设置已保存，从下一篇起生效"
+            except Exception as exc:
+                text = f"保存失败：{type(exc).__name__}"
+            top.destroy()
+            self._flash = (text, time.time() + 6, self._last_current)
+
+        buttons = tk.Frame(frame, bg=col["bg"])
+        buttons.grid(row=1 + 2 * len(user_settings.FIELDS), column=0, columnspan=3, sticky="e", pady=(pad // 2, 0))
+        for text, command in (("恢复默认", reset), ("取消", top.destroy), ("保存", save)):
+            tk.Button(buttons, text=text, command=command, font=self.f_small).pack(side="left", padx=(6, 0))
+        top.bind("<Return>", lambda e: save())
+        top.bind("<Escape>", lambda e: top.destroy())
+        top.update_idletasks()
+        x = self.root.winfo_rootx()
+        y = max(0, self.root.winfo_rooty() - top.winfo_height() - 8)
+        top.geometry(f"+{x}+{y}")
+
     def _hover_button(self, key: str, label_id: int) -> None:
         self._hover = key
         self.canvas.itemconfigure(label_id, fill=self.c["text"] if key else self.c["btn"])

package/carsi/paper_search_carsi/server.py

@@ -64,6 +64,7 @@ def carsi_download(
     batch_failed: int | None = None,
     supplements: str | None = None,
     user_wait: str | None = None,
+    diagnostics_dir: str | None = None,
 ) -> str:
     """Synchronous download entry; ``download`` is module-level so tests can stub it.
 
@@ -79,6 +80,8 @@ def carsi_download(
         kwargs = {"supplements": supplements} if supplements in ("with", "only") else {}
         if user_wait == "short":
             kwargs["user_wait"] = user_wait
+        if diagnostics_dir:
+            kwargs["diagnostics_dir"] = diagnostics_dir
         result = download(identifier, output_dir, strategy=strategy, **kwargs)
         outcome["result"] = result
         if not result.get("success"):
@@ -113,6 +116,7 @@ async def _carsi_download_with_progress(
     batch_failed: int | None = None,
     supplements: Literal["with", "only"] | None = None,
     user_wait: Literal["short"] | None = None,
+    diagnostics_dir: str | None = None,
     ctx: Context = None,
 ) -> str:
     """Download one paper by DOI through institutional access only.
@@ -129,6 +133,9 @@ async def _carsi_download_with_progress(
     (``<output_dir>/<DOI>_supplements/``, listed in the result's ``supplements``); "only"
     downloads just those, for an article whose main text is already at hand.
 
+    diagnostics_dir: optional separate directory for browser records, screenshots and
+    attachment manifests. When set, attachments go in output_dir/supplements/.
+
     user_wait: "short" when the user seems away (an earlier article of the batch waited on them
     until its time was up): each wait on the user (school login, human verification) lasts at
     most 60 s, unless someone starts typing on the login page.
@@ -140,7 +147,7 @@ async def _carsi_download_with_progress(
                                  use_vpnsci, bibtex, strategy, batch_id=batch_id, batch_index=batch_index,
                                  batch_total=batch_total, batch_done=batch_done,
                                  batch_succeeded=batch_succeeded, batch_failed=batch_failed,
-                                 supplements=supplements, user_wait=user_wait)
+                                 supplements=supplements, user_wait=user_wait, diagnostics_dir=diagnostics_dir)
     )
 
 

package/carsi/paper_search_carsi/user_settings.py

@@ -0,0 +1,55 @@
+"""The settings the progress window lets the user type in: how long a download
+waits on the school's login page and elsewhere, and how many papers each
+publisher may open per hour. They apply from the next paper."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from . import config as _config
+
+
+@dataclass(frozen=True)
+class Field:
+    name: str
+    label: str
+    key: str  # the backend's config key
+    default: int
+    low: int
+    high: int
+    unit: str
+
+
+FIELDS = (
+    Field("login", "学校登录页最多等", "browser_login_timeout", 180, 30, 1800, "秒"),
+    Field("page", "其他页面最多等", "browser_page_wait_timeout", 60, 10, 600, "秒"),
+    Field("hourly", "每家出版社每小时最多", "publisher_hourly_limit", 100, 0, 1000, "篇"),
+)
+
+
+def current() -> dict[str, int]:
+    """The values now set, by field name."""
+    config = _config.load_config()
+    return {field.name: int(config.get(field.key, field.default)) for field in FIELDS}
+
+
+def check(field: Field, text: str) -> tuple[int | None, str]:
+    """A typed value, or why it cannot be saved."""
+    try:
+        value = int(str(text).strip())
+    except ValueError:
+        value = None
+    if value is None or not field.low <= value <= field.high:
+        return None, f"请输入 {field.low} 到 {field.high} 之间的整数"
+    return value, ""
+
+
+def save(values: dict[str, int]) -> None:
+    """Save values by field name; each is checked again first."""
+    for field in FIELDS:
+        if field.name not in values:
+            continue
+        value, problem = check(field, str(values[field.name]))
+        if problem:
+            raise ValueError(f"{field.key}: {problem}")
+        _config.update_config(field.key, str(value))

package/carsi/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "paper-search-carsi"
 version = "0.1.0"
-description = "Institutional (publisher-authorized) PDF download backend for PaperSearch, carved out of scansci-pdf"
+description = "Institutional (publisher-authorized) PDF and supplementary-file download backend for PaperSearch"
 readme = "README.md"
 requires-python = ">=3.11"
 license = { file = "LICENSE" }