Annotator: side-by-side PDF view, paper upload with PMC XML

Dockerfile

@@ -0,0 +1,19 @@
+# 云部署镜像(1003, Hugging Face Spaces / Render 通用): 只含代码, 不含 schema / 论文 / 标注 / 密钥。
+# 论文和标注在 GitHub 私有仓库; schema 启动时从同一仓库读(SCHEMA_REPO_PATH); 密钥在平台的 Secrets 里。
+# 含 Docling + PyMuPDF(CPU 版 torch), 供管理员「上传论文」在服务器上转换; 模型首次转换时下载到 HF_HOME。
+FROM python:3.11-slim
+RUN apt-get update && apt-get install -y --no-install-recommends libgl1 libglib2.0-0 \
+ && rm -rf /var/lib/apt/lists/* && useradd -m -u 1000 user
+WORKDIR /srv
+COPY app/requirements.txt app/requirements-convert.txt app/
+RUN pip install --no-cache-dir -r app/requirements.txt \
+ && pip install --no-cache-dir torch torchvision --index-url https://download.pytorch.org/whl/cpu \
+ && pip install --no-cache-dir -r app/requirements-convert.txt
+COPY app app
+# 上云默认开密码; 真要关可在平台变量里覆盖 REQUIRE_PASSWORD=0
+ENV STORAGE_BACKEND=github PORT=7860 CACHE_DIR=/tmp/repl_cache REQUIRE_PASSWORD=1 \
+    SCHEMA_REPO_PATH=config/schema_0817.json HF_HOME=/tmp/hf OMP_NUM_THREADS=2 HOME=/home/user
+USER user
+EXPOSE 7860
+WORKDIR /srv/app
+CMD ["sh", "-c", "uvicorn main:app --host 0.0.0.0 --port ${PORT} --proxy-headers --forwarded-allow-ips='*'"]

README.md

@@ -1,10 +1,11 @@
 ---
 title: Annotator
-emoji: 🚀
-colorFrom: red
-colorTo: pink
+emoji: 📝
+colorFrom: gray
+colorTo: blue
 sdk: docker
+app_port: 7860
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+Annotation tool (password protected). Papers, schema and annotations live in a private data repository; nothing is stored in this Space.

app/auth.py

@@ -0,0 +1,68 @@
+"""登录: 标注人账号在环境变量 ANNOTATORS_JSON 里配置(密码只存 PBKDF2 哈希), 会话用 HMAC 签名 cookie。
+
+ANNOTATORS_JSON 示例(scripts/hash_password.py 生成哈希):
+{
+  "Rong": {"role": "admin", "pw": "pbkdf2_sha256$..."},
+  "A":    {"pw": "pbkdf2_sha256$...", "papers": ["MICCAI_3979_paper"]},
+  "B":    {"pw": "pbkdf2_sha256$..."}
+}
+papers 可选: 给了就只能看到这些论文。repo 可选: 给了就把此人标注写进那个仓库(默认写 DATA_REPO 的 annotations/<ID>/)。未配置 ANNOTATORS_JSON 且为 local 后端时 = 开放模式(同 0817 本地版, 任填 ID)。
+"""
+import base64
+import hashlib
+import hmac
+import json
+import secrets
+import time
+from typing import Optional
+
+ITERATIONS = 200_000
+COOKIE = "repl_sess"
+SESSION_TTL = 14 * 24 * 3600
+
+
+def hash_password(pw: str, salt: Optional[str] = None) -> str:
+    salt = salt or secrets.token_hex(16)
+    dk = hashlib.pbkdf2_hmac("sha256", pw.encode(), salt.encode(), ITERATIONS)
+    return f"pbkdf2_sha256${ITERATIONS}${salt}${dk.hex()}"
+
+
+def verify_password(pw: str, stored: str) -> bool:
+    try:
+        algo, it, salt, digest = stored.split("$")
+    except ValueError:
+        return False
+    if algo != "pbkdf2_sha256":
+        return False
+    dk = hashlib.pbkdf2_hmac("sha256", pw.encode(), salt.encode(), int(it))
+    return hmac.compare_digest(dk.hex(), digest)
+
+
+def _b64(b: bytes) -> str:
+    return base64.urlsafe_b64encode(b).decode().rstrip("=")
+
+
+def _unb64(s: str) -> bytes:
+    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+
+
+def sign_session(secret: str, annotator: str) -> str:
+    body = _b64(json.dumps({"a": annotator, "exp": int(time.time()) + SESSION_TTL}).encode())
+    mac = _b64(hmac.new(secret.encode(), body.encode(), hashlib.sha256).digest())
+    return f"{body}.{mac}"
+
+
+def read_session(secret: str, token: Optional[str]) -> Optional[str]:
+    if not token or "." not in token:
+        return None
+    body, mac = token.rsplit(".", 1)
+    want = _b64(hmac.new(secret.encode(), body.encode(), hashlib.sha256).digest())
+    if not hmac.compare_digest(mac, want):
+        return None
+    try:
+        data = json.loads(_unb64(body))
+    except (ValueError, json.JSONDecodeError):
+        return None
+    if data.get("exp", 0) < time.time():
+        return None
+    return data.get("a")

app/main.py

@@ -0,0 +1,666 @@
+"""Reproducibility 独立双标系统 — 后端(0925: 云部署 + GitHub 存储版)
+
+本地跑:  cd 03_annotation/app && pip install -r requirements.txt && python main.py
+         → http://localhost:8420 (默认 local 后端 + 开放模式, 行为同 0817 本地版)
+云部署:  见 ../README.md「云部署」一节(Dockerfile 在 03_annotation/)
+
+设计要点:
+- schema 驱动: 表单结构全部来自 ../schema/schema_0817.json, 改 schema 不改代码
+- 盲标: 不加载任何 LLM 预填; 标注人只能读写自己的仓库, 看不到别人的; 每条标注盖 schema_version + annotator + 时间戳章
+- grounding: evidence quote 保存时按 ground_check 同款算法(NFKC + 空白折叠)回填 char_span(折叠坐标)
+- 存储: 见 store.py。一篇 × 一人一份 JSON, 内存即时生效, 后台定时 commit 到该标注人的私有仓库;
+  events 留全程操作痕迹, 每份标注记 papers_ref(论文快照 commit), 坐标系可追溯
+"""
+import json
+import os
+import re
+import secrets
+import shutil
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+import unicodedata
+import uuid
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Optional
+
+from fastapi import Depends, FastAPI, File, Form, HTTPException, Request, Response, UploadFile
+from fastapi.responses import FileResponse, HTMLResponse, PlainTextResponse
+from pydantic import BaseModel
+
+import httpx
+
+import auth
+from store import (DocCache, GitHubAnnotationStore, GitHubPapers, LocalAnnotationStore,
+                   LocalPapers, env_flag)
+
+HERE = Path(__file__).resolve().parent
+BASE = HERE.parent                      # 03_annotation/
+PROJECT = BASE.parent                   # 1.Reproducibility/
+SCHEMA_PATH = Path(os.environ.get("SCHEMA_PATH", BASE / "schema" / "schema_0817.json"))
+# 1003: 公开部署(HF Space)时 schema 不进镜像, 启动时从私有数据仓库读: SCHEMA_REPO_PATH=config/schema_0817.json
+SCHEMA_REPO_PATH = os.environ.get("SCHEMA_REPO_PATH", "")
+
+# ---------- 配置 ----------
+
+BACKEND = os.environ.get("STORAGE_BACKEND", "local")          # local | github
+ANNOTATORS = json.loads(os.environ.get("ANNOTATORS_JSON", "") or "{}")
+# 0925: 密码默认关(只填 ID 即可进), REQUIRE_PASSWORD=1 才校验 ANNOTATORS_JSON 里的 pw; Docker 镜像默认开。
+# 配了 ANNOTATORS_JSON 时只允许名单里的 ID(防手误多出一个标注人); 没配(仅本地)则任填 ID。
+REQUIRE_PASSWORD = env_flag("REQUIRE_PASSWORD", False)
+AUTH = REQUIRE_PASSWORD and bool(ANNOTATORS)
+ID_RE = re.compile(r"^[A-Za-z0-9_-]{1,32}$")                # ID 进存储路径, 只许安全字符
+SESSION_SECRET = os.environ.get("SESSION_SECRET") or (secrets.token_hex(32) if not AUTH else "")
+COOKIE_SECURE = env_flag("COOKIE_SECURE", BACKEND == "github")
+FLUSH_SECONDS = float(os.environ.get("FLUSH_SECONDS", "15"))
+
+if AUTH and not SESSION_SECRET:
+    raise SystemExit("SESSION_SECRET is required when REQUIRE_PASSWORD=1")
+
+if BACKEND == "github":
+    # 默认一个仓库管所有: DATA_REPO 里 papers/ + annotations/<annotator>/;
+    # 某人配了 "repo" 则写进那个仓库的 annotations/(每人一仓库的旧方案, 仍支持)
+    TOKEN = os.environ["GITHUB_TOKEN"]
+    DATA_REPO = os.environ.get("DATA_REPO", "")
+    if not ANNOTATORS:
+        raise SystemExit("github backend needs ANNOTATORS_JSON")
+    locations = {}
+    for a, c in ANNOTATORS.items():
+        if c.get("repo"):
+            locations[a] = (c["repo"], "annotations")
+        elif DATA_REPO:
+            locations[a] = (DATA_REPO, f"annotations/{a}")
+        else:
+            raise SystemExit(f"annotator {a}: set DATA_REPO or give them a repo")
+    STORE = GitHubAnnotationStore(TOKEN, locations, branch=os.environ.get("DATA_BRANCH") or None)
+    PAPERS = GitHubPapers(TOKEN, os.environ.get("PAPERS_REPO") or DATA_REPO,
+                          os.environ.get("DATA_BRANCH") or "main",
+                          cache_dir=Path(os.environ.get("CACHE_DIR", "/tmp/repl_cache")),
+                          subdir=os.environ.get("PAPERS_DIR", "papers"))
+else:
+    STORE = LocalAnnotationStore(Path(os.environ.get("LOCAL_STORE_DIR", BASE / "data" / "store")))
+    PAPERS = LocalPapers(Path(os.environ.get("PAPERS_ROOT", PROJECT)),
+                         Path(os.environ.get("PAPERS_MANIFEST", BASE / "papers" / "manifest.json")))
+
+CACHE = DocCache(STORE, flush_seconds=FLUSH_SECONDS)
+
+if SCHEMA_REPO_PATH and BACKEND == "github":
+    _r = httpx.get(f"https://api.github.com/repos/{os.environ.get('PAPERS_REPO') or DATA_REPO}/contents/{SCHEMA_REPO_PATH}",
+                   params={"ref": os.environ.get("DATA_BRANCH") or "main"}, timeout=60,
+                   headers={"Authorization": f"Bearer {TOKEN}", "Accept": "application/vnd.github.raw+json"})
+    _r.raise_for_status()
+    SCHEMA = _r.json()
+else:
+    SCHEMA = json.loads(SCHEMA_PATH.read_text(encoding="utf-8"))
+SCHEMA_VERSION = SCHEMA["schema_version"]
+
+
+@asynccontextmanager
+async def lifespan(_app):
+    CACHE.start()
+    yield
+    CACHE.stop()          # 关机前把没同步的改动写回
+
+
+app = FastAPI(title="Reproducibility Annotator", lifespan=lifespan)
+
+
+# ---------- 会话 ----------
+
+def is_admin(annotator: str) -> bool:
+    return ANNOTATORS.get(annotator, {}).get("role") == "admin"
+
+
+def is_imported(annotator: str) -> bool:
+    """role = imported: 导入的标注(不在本系统里标), 不能登录、不出现在登录页, 只供 admin 只读查看。
+    是什么来源不经任何接口暴露(盲审要求), 来源记录另存, 不在数据仓库。"""
+    return ANNOTATORS.get(annotator, {}).get("role") == "imported"
+
+
+LOGIN_IDS = [a for a in ANNOTATORS if not is_imported(a)]
+
+
+def current_annotator(request: Request) -> str:
+    a = auth.read_session(SESSION_SECRET, request.cookies.get(auth.COOKIE))
+    if not a or (ANNOTATORS and a not in ANNOTATORS) or is_imported(a):
+        raise HTTPException(401, "not logged in")
+    return a
+
+
+def allowed_papers(annotator: str) -> dict:
+    """admin 看全部; 配了 papers 的人只看那些; 其余人看仓库里的论文池 papers/pool.json(1003, 大家同一个池子)。"""
+    papers = PAPERS.manifest()["papers"]
+    if is_admin(annotator):
+        return papers
+    only = ANNOTATORS.get(annotator, {}).get("papers")
+    if only is None:
+        only = PAPERS.pool()
+    if only is not None:
+        papers = {k: v for k, v in papers.items() if k in set(only)}
+    return papers
+
+
+def paper_entry(annotator: str, pid: str) -> dict:
+    papers = allowed_papers(annotator)
+    if pid not in papers:
+        raise HTTPException(404, f"unknown paper {pid}")
+    return papers[pid]
+
+
+# ---------- 标注文档 ----------
+
+def load_doc(annotator: str, paper: str) -> dict:
+    doc = CACHE.get(annotator, paper, PAPERS.ref)
+    with CACHE.lock:
+        seen = doc.setdefault("papers_refs_seen", [doc.get("papers_ref")])
+        if PAPERS.ref not in seen:
+            # 论文快照换了: char_span 坐标系可能变, 记一笔, 仲裁 / 导出时可查
+            seen.append(PAPERS.ref)
+            doc["events"].append({"ts": time.time(), "kind": "papers_ref_changed", "detail": PAPERS.ref})
+            CACHE.mark_dirty(annotator, paper, f"papers_ref_changed {PAPERS.ref[:12]}")
+    return doc
+
+
+def log_event(doc: dict, annotator: str, paper: str, kind: str, detail: str = ""):
+    doc["events"].append({"ts": time.time(), "kind": kind, "detail": detail[:500]})
+    CACHE.mark_dirty(annotator, paper, f"{kind} {detail[:80]}")
+
+
+# ---------- grounding (ground_check 同款) ----------
+
+def fold(t: str) -> str:
+    t = unicodedata.normalize("NFKC", t)
+    return re.sub(r"\s+", " ", t).strip()
+
+
+_FOLDED = {}
+
+
+def folded_fulltext(annotator: str, pid: str) -> str:
+    rel = paper_entry(annotator, pid)["fulltext"]
+    if rel not in _FOLDED:
+        _FOLDED[rel] = fold(PAPERS.text(rel))
+    return _FOLDED[rel]
+
+
+def relaxed_find(text: str, q: str):
+    """markdown 容忍匹配: 渲染视图选出的 quote 不含标记符(** ` | #), 源文件里有。
+    在 quote 每个字符间允许穿插标记符, 空格处允许穿插空白+标记符, 返回源文件折叠坐标。"""
+    parts = []
+    for ch in q:
+        if ch == " ":
+            parts.append(r"[\s|*_`#]+")
+        else:
+            parts.append(re.escape(ch) + r"[|*_`]*")
+    m = re.compile("".join(parts)).search(text)
+    return (m.start(), m.end()) if m else None
+
+
+_LAYOUT = {}
+
+
+def fold_with_map(raw: str):
+    """逐字符版 fold, 同时记每个折叠字符对应的原文下标。只用来把 quote 落到 layout 块上;
+    char_span 仍按 fold() 整串口径算, 两者在组合字符处可能差一两位, 不影响定位到哪一块。"""
+    out, idx = [], []
+    for i, ch in enumerate(raw):
+        n = unicodedata.normalize("NFKC", ch)
+        if not n.strip():
+            if out and out[-1] != " ":
+                out.append(" ")
+                idx.append(i)
+            continue
+        for c in n:
+            out.append(c)
+            idx.append(i)
+    if out and out[-1] == " ":
+        out.pop()
+        idx.pop()
+    return "".join(out), idx
+
+
+def paper_layout(annotator: str, pid: str):
+    """layout.json(1003 起): 人读 md 的每块 → PDF (page, bbox)。没有 layout 的论文(旧 txt / 0817 md)返回 None。"""
+    e = paper_entry(annotator, pid)
+    rel = e.get("layout")
+    if not rel:
+        return None
+    if rel not in _LAYOUT:
+        lay = json.loads(PAPERS.text(rel))
+        folded, idx = fold_with_map(PAPERS.text(e["fulltext"]))
+        _LAYOUT[rel] = {"raw": lay, "folded": folded, "idx": idx}
+    return _LAYOUT[rel]
+
+
+def pdf_anchor_for(lay: dict, quote: str):
+    """quote → 覆盖它的 layout 块 → 这些块在 PDF 上的框。找不到返回 None。"""
+    text, q = lay["folded"], fold(quote)
+    i = text.find(q)
+    sp = (i, i + len(q)) if i >= 0 else relaxed_find(text, q)
+    if not sp or sp[1] <= sp[0]:
+        return None
+    a, b = lay["idx"][sp[0]], lay["idx"][sp[1] - 1] + 1
+    blocks = [blk for blk in lay["raw"]["blocks"] if blk["start"] < b and blk["end"] > a]
+    boxes = [bx for blk in blocks for bx in blk["boxes"]]
+    return {"blocks": [blk["id"] for blk in blocks], "boxes": boxes} if blocks else None
+
+
+def ground_evidence(annotator: str, pid: str, payload: dict) -> dict:
+    """对 payload.evidence 里每条 quote 回填折叠坐标 char_span; 找不到标 grounded=false 并降级提示。
+    两层: ① NFKC+折叠后精确子串(与 ground_check 同口径) ② markdown 容忍匹配(md 语料, 0817 加)。
+    有 layout 的论文另回填 pdf_anchor(块 id + PDF 框); 在 PDF 上直接划选的证据(origin=pdf)
+    保留前端记下的精确框, 即使文本里对不上(转换损坏)也不丢位置。"""
+    text = folded_fulltext(annotator, pid)
+    lay = paper_layout(annotator, pid)
+    for ev in payload.get("evidence", []):
+        q = fold(ev.get("quote", ""))
+        if lay and q and ev.get("origin") != "pdf":
+            ev["pdf_anchor"] = pdf_anchor_for(lay, q)
+        if not q:
+            ev["grounded"] = False
+            ev["char_span"] = None
+            continue
+        i = text.find(q)
+        if i >= 0:
+            ev["char_span"] = [i, i + len(q)]
+            ev["grounded"] = True
+            ev.pop("match", None)
+        else:
+            sp = relaxed_find(text, q)
+            if sp:
+                ev["char_span"] = [sp[0], sp[1]]
+                ev["grounded"] = True
+                ev["match"] = "relaxed"   # 命中含 markdown 标记的源文本
+            else:
+                ev["char_span"] = None
+                ev["grounded"] = False   # 失配降级, 前端提示核对
+    return payload
+
+
+# ---------- API: 登录 ----------
+
+@app.get("/", response_class=HTMLResponse)
+def index():
+    return (HERE / "static" / "index.html").read_text(encoding="utf-8")
+
+
+@app.get("/api/config")
+def get_config():
+    return {"auth": AUTH, "backend": BACKEND, "schema_version": SCHEMA_VERSION,
+            "annotators": [] if AUTH else LOGIN_IDS}
+
+
+class Login(BaseModel):
+    annotator: str
+    password: str = ""
+
+
+@app.post("/api/login")
+def login(body: Login, response: Response):
+    a = body.annotator.strip()
+    if not ID_RE.match(a):
+        raise HTTPException(400, "annotator ID: letters, digits, _ or - only")
+    if ANNOTATORS and a not in ANNOTATORS:
+        raise HTTPException(401, "unknown annotator ID")
+    if is_imported(a):
+        raise HTTPException(403, "imported annotator — cannot sign in")
+    if AUTH and not auth.verify_password(body.password, ANNOTATORS[a].get("pw", "")):
+        time.sleep(1.0)       # 放慢暴力尝试
+        raise HTTPException(401, "wrong annotator ID or password")
+    response.set_cookie(auth.COOKIE, auth.sign_session(SESSION_SECRET, a), max_age=auth.SESSION_TTL,
+                        httponly=True, samesite="lax", secure=COOKIE_SECURE)
+    return {"annotator": a, "admin": is_admin(a)}
+
+
+@app.post("/api/logout")
+def logout(response: Response):
+    response.delete_cookie(auth.COOKIE)
+    return {"ok": True}
+
+
+@app.get("/api/me")
+def me(annotator: str = Depends(current_annotator)):
+    out = {"annotator": annotator, "admin": is_admin(annotator)}
+    if out["admin"]:
+        out["annotators"] = list(ANNOTATORS)
+    return out
+
+
+# ---------- API: schema / 论文 ----------
+
+@app.get("/api/schema")
+def get_schema(_a: str = Depends(current_annotator)):
+    return SCHEMA
+
+
+def clean_title(pid: str, entry: dict) -> str:
+    """manifest 里旧的 title 是全文首行, MICCAI 是 "<!-- image -->"、openreview 有页码; publish_papers 新版已写干净的。"""
+    t = (entry.get("title") or "").strip()
+    t = re.sub(r"^#+\s*", "", t)
+    if not t or t.startswith("<!--") or t.isdigit():
+        return pid
+    return t
+
+
+@app.get("/api/papers")
+def get_papers(annotator: str = Depends(current_annotator)):
+    papers = {pid: {**e, "title": clean_title(pid, e)} for pid, e in allowed_papers(annotator).items()}
+    out = {"papers": papers, "papers_ref": PAPERS.ref}
+    if is_admin(annotator):
+        out["pool"] = PAPERS.pool()
+    return out
+
+
+def filled(payload: dict) -> bool:
+    # 外键 / 轴 / no_anchor 也算填了(F2、M7、D24、R3、D27 常常只有这些)
+    return bool(payload.get("status") or payload.get("value") or payload.get("evidence")
+                or payload.get("fk") or payload.get("axes") or payload.get("no_anchor"))
+
+
+@app.get("/api/overview")
+def overview(annotator: Optional[str] = None, me_: str = Depends(current_annotator)):
+    """首页卡片用: 每篇论文 × 当前标注人(admin 可指定别人)按记录类型的记录数 / 已填字段数。
+    只加载存储里已有的文档(一次 list), 没标过的论文不打 GitHub。"""
+    who = annotator if (annotator and is_admin(me_)) else me_
+    existing = {Path(n).stem for n in STORE.list(who)}
+    with CACHE.lock:
+        existing |= {p for (a, p) in CACHE.docs if a == who}
+    out = {}
+    for pid in allowed_papers(me_):
+        blocks, total, last = {}, 0, None
+        if pid in existing:
+            doc = load_doc(who, pid)
+            with CACHE.lock:
+                for uid, r in doc["records"].items():
+                    if r.get("deleted"):
+                        continue
+                    n = sum(1 for f in doc["fields"].get(uid, {}).values() if filled(f["payload"]))
+                    b = blocks.setdefault(r["rtype"], {"records": 0, "filled": 0})
+                    b["records"] += 1
+                    b["filled"] += n
+                    total += n
+                last = max((e["ts"] for e in doc["events"]), default=None)
+        out[pid] = {"blocks": blocks, "filled": total, "last_ts": last}
+    return {"annotator": who, "papers": out}
+
+
+@app.get("/api/paper/{pid}/text", response_class=PlainTextResponse)
+def get_text(pid: str, annotator: str = Depends(current_annotator)):
+    return PAPERS.text(paper_entry(annotator, pid)["fulltext"])
+
+
+@app.get("/api/paper/{pid}/layout")
+def get_layout(pid: str, annotator: str = Depends(current_annotator)):
+    lay = paper_layout(annotator, pid)
+    if not lay:
+        raise HTTPException(404, "no layout for this paper")
+    return lay["raw"]
+
+
+@app.get("/api/paper/{pid}/pdf")
+def get_pdf(pid: str, annotator: str = Depends(current_annotator)):
+    entry = paper_entry(annotator, pid)
+    if not entry.get("pdf"):
+        raise HTTPException(404, "no pdf for this paper")
+    return FileResponse(PAPERS.pdf_path(entry["pdf"]), media_type="application/pdf")
+
+
+# ---------- API: 标注 ----------
+
+@app.get("/api/state")
+def get_state(paper: str, annotator: Optional[str] = None, me_: str = Depends(current_annotator)):
+    # 标注人只能读自己的; admin 可以只读查看别人的(仲裁用)
+    who = annotator if (annotator and is_admin(me_)) else me_
+    paper_entry(me_, paper)
+    doc = load_doc(who, paper)
+    with CACHE.lock:
+        recs = sorted(({"uid": uid, "rtype": r["rtype"], "extra": r.get("extra", {}),
+                        "created_ts": r["created_ts"]}
+                       for uid, r in doc["records"].items() if not r.get("deleted")),
+                      key=lambda r: r["created_ts"])
+        flds = {uid: {fid: f["payload"] for fid, f in m.items()} for uid, m in doc["fields"].items()}
+    return {"records": recs, "fields": flds, "schema_version": SCHEMA_VERSION,
+            "annotator": who, "read_only": who != me_}
+
+
+class RecordOp(BaseModel):
+    paper: str
+    action: str            # create / delete / extra
+    annotator: Optional[str] = None     # 旧前端兼容, 忽略; 身份以会话为准
+    rtype: Optional[str] = None
+    uid: Optional[str] = None
+    extra: Optional[dict] = None
+
+
+@app.post("/api/record")
+def record_op(op: RecordOp, annotator: str = Depends(current_annotator)):
+    paper_entry(annotator, op.paper)
+    doc = load_doc(annotator, op.paper)
+    now = time.time()
+    with CACHE.lock:
+        if op.action == "create":
+            uid = str(uuid.uuid4())[:8]
+            doc["records"][uid] = {"rtype": op.rtype, "extra": op.extra or {}, "deleted": 0,
+                                   "created_ts": now, "updated_ts": now}
+            log_event(doc, annotator, op.paper, "record_create", f"{op.rtype}:{uid}")
+            return {"uid": uid}
+        rec = doc["records"].get(op.uid or "")
+        if rec is None:
+            raise HTTPException(404, "unknown record")
+        if op.action == "delete":
+            rec["deleted"] = 1
+            rec["updated_ts"] = now
+            log_event(doc, annotator, op.paper, "record_delete", op.uid)
+            return {"ok": True}
+        if op.action == "extra":
+            rec["extra"] = op.extra or {}
+            rec["updated_ts"] = now
+            log_event(doc, annotator, op.paper, "record_extra", op.uid)
+            return {"ok": True}
+    raise HTTPException(400, "bad action")
+
+
+class FieldSave(BaseModel):
+    paper: str
+    record_uid: str
+    field_id: str
+    payload: dict
+    annotator: Optional[str] = None     # 同上, 忽略
+
+
+@app.post("/api/field")
+def field_save(s: FieldSave, annotator: str = Depends(current_annotator)):
+    payload = ground_evidence(annotator, s.paper, s.payload)
+    doc = load_doc(annotator, s.paper)
+    with CACHE.lock:
+        if s.record_uid not in doc["records"]:
+            raise HTTPException(404, "unknown record")
+        doc["fields"].setdefault(s.record_uid, {})[s.field_id] = {
+            "payload": payload, "schema_version": SCHEMA_VERSION, "updated_ts": time.time()}
+        log_event(doc, annotator, s.paper, "field_save", f"{s.record_uid}.{s.field_id}")
+    return {"payload": payload}
+
+
+@app.get("/api/progress")
+def progress(paper: str, annotator: str = Depends(current_annotator)):
+    doc = load_doc(annotator, paper)
+    with CACHE.lock:
+        n = sum(len(m) for m in doc["fields"].values())
+    return {"fields_touched": n}
+
+
+@app.get("/api/sync")
+def sync_status(annotator: str = Depends(current_annotator)):
+    return {**CACHE.status(annotator), "backend": BACKEND}
+
+
+@app.post("/api/sync")
+def sync_now(annotator: str = Depends(current_annotator)):
+    CACHE.flush()
+    return {**CACHE.status(annotator), "backend": BACKEND}
+
+
+# ---------- API: admin ----------
+
+@app.get("/api/admin/export")
+def admin_export(annotator: str = Depends(current_annotator)):
+    """全部标注人 × 全部论文的原始文档(先把内存里的改动写回, 再从存储读)。"""
+    if not is_admin(annotator):
+        raise HTTPException(403, "admin only")
+    CACHE.flush()
+    people = list(ANNOTATORS) if ANNOTATORS else sorted(
+        p.name for p in getattr(STORE, "root", Path("/nonexistent")).glob("*") if p.is_dir())
+    out = {}
+    for a in people:
+        for name in STORE.list(a):
+            data, _ = STORE.read(a, name)
+            if data:
+                out.setdefault(a, {})[Path(name).stem] = json.loads(data)
+    return {"exported": time.time(), "papers_ref": PAPERS.ref, "schema_version": SCHEMA_VERSION,
+            "annotations": out}
+
+
+# ---------- API: admin 上传论文(1003) ----------
+# 上传 PDF 和 / 或填 PMCID / DOI / PMID → 子进程跑 textconv.py(PMC 开放获取有 XML 就用 XML, 否则 Docling)
+# → 一个 commit 写进 papers/<pid>/(只增不改) → 可选加入论文池。一次只转一篇(Docling 吃内存)。
+
+CONVERT_PYTHON = os.environ.get("CONVERT_PYTHON", sys.executable)
+MAX_UPLOAD_MB = float(os.environ.get("MAX_UPLOAD_MB", "60"))
+JOBS: dict = {}
+_CONVERT_LOCK = threading.Lock()
+
+
+def _abstract(md: str) -> str:
+    paras = [p.strip() for p in md.split("\n\n") if p.strip()]
+    for i, p in enumerate(paras):
+        if re.match(r"^#+\s*abstract\b", p, re.I) and i + 1 < len(paras):
+            a = paras[i + 1]
+            break
+        m = re.match(r"^abstract[.:\s]+(.{80,})", p, re.I | re.S)
+        if m:
+            a = m.group(1)
+            break
+    else:
+        a = next((p for p in paras if not p.startswith(("#", "|", "[")) and len(p) > 200), "")
+    a = re.sub(r"\s+", " ", a)
+    return a[:400].rsplit(" ", 1)[0] + " …" if len(a) > 400 else a
+
+
+def _new_pid(meta: dict, filename: str) -> str:
+    if meta.get("pmcid"):
+        return f"PMC_{meta['pmcid']}"
+    stem = re.sub(r"[^A-Za-z0-9]+", "-", Path(filename or "paper").stem).strip("-")[:40] or "paper"
+    pid, n, have = f"UP_{stem}", 2, PAPERS.manifest()["papers"]
+    while pid in have:
+        pid, n = f"UP_{stem}-{n}", n + 1
+    return pid
+
+
+def _run_upload(jid: str, work: Path, pdf: Optional[Path], ident: str, title: str, venue: str,
+                to_pool: bool, who: str, filename: str):
+    job = JOBS[jid]
+    try:
+        with _CONVERT_LOCK:
+            job["status"] = "running"
+            out = work / "out"
+            cmd = [CONVERT_PYTHON, str(HERE / "textconv.py"), "job", "--out", str(out)]
+            cmd += ["--pdf", str(pdf)] if pdf else []
+            cmd += ["--ident", ident] if ident else []
+            proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True)
+            for line in proc.stdout:
+                line = line.rstrip()
+                if line and not re.search(r"warn|it/s|^\s|^\[|INFO|DEBUG|torch|conv2d", line, re.I):
+                    job["log"].append(line[:300])
+            if proc.wait() != 0 or not (out / "meta.json").exists():
+                err = next((l for l in reversed(job["log"]) if l.startswith("ERROR")), "conversion failed")
+                raise RuntimeError(err.replace("ERROR: ", ""))
+        meta = json.loads((out / "meta.json").read_text(encoding="utf-8"))
+        pid = _new_pid(meta, filename)
+        if pid in PAPERS.manifest()["papers"]:
+            raise RuntimeError(f"{pid} is already in the system")
+        md = (out / "fulltext.md").read_text(encoding="utf-8")
+        files = {"fulltext.md": md.encode("utf-8"), "layout.json": (out / "layout.json").read_bytes(),
+                 "paper.pdf": (out / "paper.pdf").read_bytes()}
+        entry = {"fulltext": "fulltext.md", "pdf": "paper.pdf", "layout": "layout.json",
+                 "venue": venue or ("PMC" if meta.get("pmcid") else "Upload"),
+                 "title": title or meta.get("title") or Path(filename or pid).stem,
+                 "abstract": _abstract(md), "text_source": meta["source"],
+                 "pmcid": meta.get("pmcid"), "doi": meta.get("doi"), "license": meta.get("license"),
+                 "uploaded_by": who, "uploaded_ts": time.time(), "upload_name": filename or None}
+        job["log"].append("saving to the data repository…")
+        PAPERS.add_paper(pid, files, entry, message=f"papers: add {pid} ({meta['source']}, uploaded by {who})")
+        if to_pool:
+            pool = PAPERS.pool() or []
+            if pid not in pool:
+                PAPERS.set_pool(pool + [pid], message=f"papers: add {pid} to the annotator pool")
+        job.update(status="done", pid=pid, title=entry["title"], source=meta["source"])
+        job["log"].append(f"done → {pid}" + (" (added to the pool)" if to_pool else ""))
+    except Exception as e:  # noqa: BLE001
+        job.update(status="error", error=str(e))
+    finally:
+        shutil.rmtree(work, ignore_errors=True)
+
+
+def require_admin(annotator: str = Depends(current_annotator)) -> str:
+    if not is_admin(annotator):
+        raise HTTPException(403, "admin only")
+    return annotator
+
+
+@app.post("/api/admin/upload")
+async def admin_upload(pdf: Optional[UploadFile] = File(None), ident: str = Form(""), title: str = Form(""),
+                       venue: str = Form(""), add_to_pool: bool = Form(True), who: str = Depends(require_admin)):
+    ident = ident.strip()
+    if not pdf and not ident:
+        raise HTTPException(400, "upload a PDF or give a PMCID / DOI / PMID")
+    work = Path(tempfile.mkdtemp(prefix="upload_"))
+    path, filename = None, ""
+    if pdf:
+        data = await pdf.read()
+        if len(data) > MAX_UPLOAD_MB * 1e6:
+            raise HTTPException(413, f"PDF larger than {MAX_UPLOAD_MB:.0f} MB")
+        if not data.startswith(b"%PDF"):
+            raise HTTPException(400, "that file is not a PDF")
+        filename = Path(pdf.filename or "paper.pdf").name
+        path = work / "upload.pdf"
+        path.write_bytes(data)
+    jid = uuid.uuid4().hex[:10]
+    JOBS[jid] = {"id": jid, "status": "queued", "log": [], "file": filename, "ident": ident,
+                 "by": who, "ts": time.time()}
+    threading.Thread(target=_run_upload, daemon=True,
+                     args=(jid, work, path, ident, title.strip(), venue.strip(), add_to_pool, who, filename)).start()
+    return JOBS[jid]
+
+
+@app.get("/api/admin/jobs")
+def admin_jobs(_a: str = Depends(require_admin)):
+    return {"jobs": sorted(JOBS.values(), key=lambda j: -j["ts"])[:30]}
+
+
+class PoolOp(BaseModel):
+    paper: str
+    include: bool
+
+
+@app.post("/api/admin/pool")
+def admin_pool(op: PoolOp, who: str = Depends(require_admin)):
+    if op.paper not in PAPERS.manifest()["papers"]:
+        raise HTTPException(404, "unknown paper")
+    pool = list(PAPERS.pool() or [])
+    if op.include and op.paper not in pool:
+        pool.append(op.paper)
+    elif not op.include and op.paper in pool:
+        pool.remove(op.paper)
+    else:
+        return {"pool": pool}
+    PAPERS.set_pool(pool, message=f"papers: {'add' if op.include else 'remove'} {op.paper} "
+                                  f"{'to' if op.include else 'from'} the annotator pool ({who})")
+    return {"pool": pool}
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", "8420")))

app/requirements-convert.txt

@@ -0,0 +1,2 @@
+docling>=2.50
+pymupdf>=1.24

app/requirements.txt

@@ -0,0 +1,5 @@
+fastapi>=0.110
+uvicorn>=0.29
+pydantic>=2
+httpx>=0.27
+python-multipart>=0.0.9

app/static/index.html

@@ -0,0 +1,1215 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Reproducibility Annotator</title>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.min.js"></script>
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<style>
+  :root{
+    --bg:#f6f7f9; --panel:#ffffff; --ink:#1d2430; --muted:#6b7686; --line:#e3e7ee;
+    --accent:#d97706; --accent-soft:#fff3e0; --blue:#2563eb; --green:#15803d; --red:#b91c1c;
+    --na:#eef0f4;
+  }
+  *{box-sizing:border-box}
+  html,body{height:100%;margin:0}
+  body{font:14px/1.55 -apple-system,"PingFang SC","Helvetica Neue",sans-serif;color:var(--ink);background:var(--bg)}
+  button{font:inherit;cursor:pointer;border:1px solid var(--line);background:#fff;border-radius:6px;padding:4px 10px}
+  button:hover{border-color:#b9c2d0}
+  button.primary{background:var(--accent);border-color:var(--accent);color:#fff}
+  select,input[type=text],textarea{font:inherit;border:1px solid var(--line);border-radius:6px;padding:4px 8px;background:#fff;color:var(--ink);width:100%}
+  textarea{resize:vertical;min-height:34px}
+  .muted{color:var(--muted)}
+  /* ---------- login ---------- */
+  #login{position:fixed;inset:0;background:var(--bg);display:flex;align-items:center;justify-content:center;z-index:50}
+  #login .box{background:var(--panel);border:1px solid var(--line);border-radius:12px;padding:28px 32px;width:420px;box-shadow:0 8px 30px rgba(0,0,0,.06)}
+  #login h1{font-size:18px;margin:0 0 4px}
+  #login .sub{font-size:12px;color:var(--muted);margin-bottom:18px}
+  #login label{display:block;font-size:12px;color:var(--muted);margin:12px 0 4px}
+  #login input[type=password]{font:inherit;border:1px solid var(--line);border-radius:6px;padding:4px 8px;width:100%}
+  .login-err{color:var(--red);font-size:12px;min-height:16px;margin-top:8px}
+  /* ---------- home ---------- */
+  :root{--c-l1:#475569;--c-dataset:#2563eb;--c-split:#0891b2;--c-asset:#0d9488;--c-model:#7c3aed;--c-result:#d97706;--c-claim:#e11d48}
+  #home{display:none;min-height:100vh}
+  .topbar{position:sticky;top:0;z-index:20;display:flex;align-items:center;gap:12px;padding:10px 24px;background:rgba(255,255,255,.92);backdrop-filter:blur(8px);border-bottom:1px solid var(--line)}
+  .brand{font-weight:700;font-size:15px;letter-spacing:-.01em}
+  .brand small{font-weight:400;color:var(--muted);margin-left:6px}
+  .topbar .spacer{flex:1}
+  .topbar .chip{font-size:12px;background:var(--na);border-radius:99px;padding:3px 10px}
+  .topbar select{width:auto;font-size:12px;padding:3px 8px}
+  .home-wrap{max-width:1320px;margin:0 auto;padding:24px}
+  .home-head{display:flex;align-items:flex-end;gap:16px;flex-wrap:wrap;margin-bottom:6px}
+  .home-head h2{margin:0;font-size:22px;letter-spacing:-.02em}
+  .home-stats{color:var(--muted);font-size:13px}
+  .blind-note{font-size:12px;color:var(--muted);margin:4px 0 18px}
+  .filters{display:flex;gap:10px;align-items:center;flex-wrap:wrap;margin-bottom:18px}
+  .filters input{max-width:320px}
+  .pill{font-size:12px;border:1px solid var(--line);background:#fff;border-radius:99px;padding:4px 12px;cursor:pointer;color:var(--muted);white-space:nowrap}
+  .pill.on{background:var(--ink);border-color:var(--ink);color:#fff}
+  .grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(300px,1fr));gap:16px}
+  .pcard{background:var(--panel);border:1px solid var(--line);border-radius:14px;padding:16px 16px 14px;cursor:pointer;display:flex;flex-direction:column;gap:8px;transition:box-shadow .15s,transform .15s,border-color .15s;min-height:230px}
+  .pcard:hover{box-shadow:0 10px 28px rgba(15,23,42,.08);transform:translateY(-2px);border-color:#cfd6e2}
+  .pcard .meta{display:flex;align-items:center;gap:8px;font-size:11.5px;color:var(--muted)}
+  .venue{font-size:11px;font-weight:600;border-radius:6px;padding:2px 8px;background:var(--na);color:var(--ink)}
+  .pcard h3{margin:0;font-size:14.5px;line-height:1.4;display:-webkit-box;-webkit-line-clamp:3;-webkit-box-orient:vertical;overflow:hidden}
+  .pcard .abs{font-size:12.5px;color:var(--muted);line-height:1.5;display:-webkit-box;-webkit-line-clamp:3;-webkit-box-orient:vertical;overflow:hidden;flex:1}
+  .pcard .foot{display:flex;align-items:center;gap:10px;border-top:1px dashed var(--line);padding-top:10px}
+  .blocks{display:flex;gap:3px;flex:1}
+  .blk{flex:1;height:22px;border-radius:5px;background:var(--na);font-size:10px;font-weight:600;color:#9aa3b2;display:flex;align-items:center;justify-content:center}
+  .blk.on{color:#fff}
+  .status{font-size:11px;border-radius:99px;padding:2px 9px;white-space:nowrap}
+  .status.todo{background:var(--na);color:var(--muted)}
+  .status.doing{background:var(--accent-soft);color:var(--accent)}
+  .empty{color:var(--muted);text-align:center;padding:60px 0}
+  /* ---------- 1003: admin upload + pool ---------- */
+  .pool-pill{font-size:11px;border-radius:99px;padding:2px 9px;border:1px solid var(--line);background:#fff;color:var(--muted);cursor:pointer;white-space:nowrap}
+  .pool-pill.on{background:#e7f6ec;border-color:#bfe3cb;color:var(--green)}
+  .src-tag{font-size:10.5px;border-radius:4px;padding:1px 6px;background:var(--na);color:var(--muted)}
+  #upload{display:none;position:fixed;inset:0;z-index:70;background:rgba(15,23,42,.45);align-items:center;justify-content:center;padding:24px}
+  #upload .box{background:var(--panel);border-radius:14px;width:min(640px,100%);max-height:100%;overflow:auto;padding:22px 24px;box-shadow:0 30px 80px rgba(0,0,0,.25)}
+  #upload h3{margin:0 0 4px;font-size:17px}
+  #upload .sub{font-size:12.5px;color:var(--muted);margin-bottom:14px;line-height:1.5}
+  #upload label{display:block;font-size:12px;color:var(--muted);margin:10px 0 4px}
+  #upload .row{display:flex;gap:10px}
+  #upload .row>div{flex:1}
+  #upload .acts{display:flex;align-items:center;gap:10px;margin-top:16px}
+  #up-err{color:var(--red);font-size:12px}
+  .job{border:1px solid var(--line);border-radius:10px;padding:8px 10px;margin-top:10px;font-size:12.5px}
+  .job .st{font-weight:600}
+  .job .st.done{color:var(--green)} .job .st.error{color:var(--red)} .job .st.running,.job .st.queued{color:var(--accent)}
+  .job pre{margin:6px 0 0;font-size:11.5px;white-space:pre-wrap;color:var(--muted);font-family:ui-monospace,monospace;max-height:140px;overflow:auto}
+  /* ---------- detail modal ---------- */
+  #detail{display:none;position:fixed;inset:0;z-index:60;background:rgba(15,23,42,.45);align-items:center;justify-content:center;padding:24px}
+  #detail .modal{background:var(--bg);border-radius:16px;width:min(1400px,100%);height:min(920px,100%);display:flex;flex-direction:column;overflow:hidden;box-shadow:0 30px 80px rgba(0,0,0,.25)}
+  .m-head{display:flex;align-items:flex-start;gap:14px;padding:16px 20px;background:var(--panel);border-bottom:1px solid var(--line)}
+  .m-head h2{margin:4px 0 0;font-size:17px;line-height:1.35}
+  .m-head .x{margin-left:auto;font-size:18px;line-height:1;padding:4px 10px}
+  .m-body{flex:1;display:flex;min-height:0}
+  .m-pdf{flex:1.1;min-width:0;border-right:1px solid var(--line);display:flex;flex-direction:column;background:#525659}
+  .m-pdf iframe{flex:1;border:0;width:100%}
+  .m-pdf .nopdf{color:#fff;margin:auto;opacity:.8}
+  .m-side{flex:1;min-width:0;display:flex;flex-direction:column}
+  .m-cards{flex:1;overflow:auto;padding:16px 18px;display:grid;grid-template-columns:1fr 1fr;gap:12px;align-content:start}
+  .bcard{background:var(--panel);border:1px solid var(--line);border-radius:12px;padding:12px 14px;border-top:3px solid var(--bc,var(--line))}
+  .bcard.wide{grid-column:1/-1}
+  .bcard h4{margin:0 0 2px;font-size:13px;display:flex;align-items:center;gap:6px}
+  .bcard .sub{font-size:11.5px;color:var(--muted);margin-bottom:8px}
+  .bcard ul{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:6px}
+  .bcard li{font-size:12.5px;line-height:1.45;background:#fafbfd;border:1px solid #eef1f6;border-radius:8px;padding:6px 8px}
+  .bcard li .k{color:var(--muted);font-size:11px;margin-right:4px}
+  .bcard li .tag{font-size:10.5px;border-radius:4px;padding:0 5px;background:var(--na);color:var(--muted);margin-left:4px;white-space:nowrap;display:inline-block}
+  .bcard .none{font-size:12px;color:#a0a8b6;font-style:italic}
+  .bar{height:4px;background:var(--na);border-radius:99px;overflow:hidden;margin:6px 0 8px}
+  .bar i{display:block;height:100%;background:var(--bc)}
+  .m-foot{display:flex;align-items:center;gap:10px;padding:12px 18px;background:var(--panel);border-top:1px solid var(--line)}
+  .m-foot .spacer{flex:1}
+  .m-foot button.primary{padding:7px 18px;font-weight:600;white-space:nowrap}
+  .m-foot a{white-space:nowrap}
+  @media (max-width:900px){.m-body{flex-direction:column}.m-pdf{flex:none;height:45%}.m-cards{grid-template-columns:1fr}}
+  header .chip.sync{cursor:pointer}
+  header .chip.sync.ok{background:#e7f6ec;color:var(--green)}
+  header .chip.sync.pending{background:var(--accent-soft);color:var(--accent)}
+  header .chip.sync.err{background:#fde8e8;color:var(--red)}
+  /* ---------- layout ---------- */
+  #app{display:none;height:100vh;flex-direction:column}
+  header{display:flex;align-items:center;gap:14px;padding:8px 14px;background:var(--panel);border-bottom:1px solid var(--line)}
+  header .title{font-weight:600}
+  header .chip{font-size:12px;background:var(--na);border-radius:99px;padding:2px 10px}
+  header .spacer{flex:1}
+  #main{flex:1;display:flex;min-height:0}
+  #left,#right{min-width:0;display:flex;flex-direction:column}
+  #left{width:46%;border-right:1px solid var(--line)}
+  #right{flex:1}
+  .tabs{display:flex;gap:2px;padding:6px 10px 0;background:var(--panel);border-bottom:1px solid var(--line);flex-wrap:wrap}
+  .tab{padding:5px 12px;border:1px solid transparent;border-bottom:none;border-radius:8px 8px 0 0;font-size:13px;color:var(--muted);cursor:pointer;white-space:nowrap}
+  .tab.on{background:var(--bg);border-color:var(--line);color:var(--ink);font-weight:600}
+  .tab .cnt{font-size:11px;color:var(--muted)}
+  .pane{flex:1;overflow:auto;min-height:0}
+  /* ---------- left ---------- */
+  #textpane{padding:16px 20px;white-space:pre-wrap;font-size:13.5px;line-height:1.75;user-select:text}
+  #textpane mark{background:#ffe9a8;border-radius:3px}
+  #textpane table{border-collapse:collapse;margin:10px 0;font-size:12.5px;display:block;overflow-x:auto;max-width:100%}
+  #textpane th,#textpane td{border:1px solid var(--line);padding:3px 8px;text-align:left;white-space:nowrap}
+  #textpane th{background:#fbfcfe;font-weight:600}
+  #textpane h2,#textpane h3,#textpane h4,#textpane h5,#textpane h6{margin:14px 0 6px;line-height:1.3}
+  #textpane h2{font-size:16px} #textpane h3{font-size:14.5px} #textpane h4,#textpane h5,#textpane h6{font-size:13.5px}
+  #textpane p{margin:6px 0}
+  #textpane .flash{background:#ffe9a8;transition:background .3s}
+  /* 1003: PDF ↔ text side by side */
+  #splitter{flex:none;width:6px;cursor:col-resize;background:var(--line)}
+  #splitter:hover,#splitter.drag{background:var(--accent)}
+  .lpane{flex:1;display:flex;min-height:0}
+  .lpane>div{flex:1;min-width:0;overflow:auto}
+  #pdfview{background:#525659;padding:12px;position:relative;border-right:1px solid var(--line)}
+  #pdfview .nopdf{color:#fff;opacity:.8;text-align:center;margin-top:40px}
+  #pdfview .pg{position:relative;margin:0 auto 12px;background:#fff;box-shadow:0 1px 4px rgba(0,0,0,.35)}
+  #pdfview .pg canvas{position:absolute;left:0;top:0}
+  .textLayer{position:absolute;inset:0;overflow:hidden;line-height:1;text-size-adjust:none;forced-color-adjust:none;transform-origin:0 0;z-index:2}
+  .textLayer span,.textLayer br{color:transparent;position:absolute;white-space:pre;cursor:text;transform-origin:0% 0%}
+  .textLayer ::selection{background:rgba(37,99,235,.3)}
+  .textLayer .endOfContent{display:block;position:absolute;inset:100% 0 0;z-index:-1;cursor:default;user-select:none}
+  .hl-layer{position:absolute;inset:0;pointer-events:none;z-index:3}
+  .hl-layer i{position:absolute;border-radius:3px}
+  .hl-layer i.blk{background:rgba(217,119,6,.12);outline:2px solid rgba(217,119,6,.75)}
+  .hl-layer i.ev{background:rgba(250,204,21,.35);outline:2px solid #eab308}
+  #textpane .tb{border-left:3px solid transparent;padding-left:8px;margin-left:-11px;border-radius:2px}
+  #textpane.linked .tb:hover{border-left-color:#d6dbe4}
+  #textpane .tb.cur{border-left-color:var(--accent);background:#fffaf0}
+  #textpane .tb.k-figure,#textpane .tb.k-formula{color:var(--muted);font-style:italic}
+  #textpane .tb.k-caption{font-size:12.5px;font-weight:600;color:#374151}
+  #textpane .tb.k-footnote,#textpane .tb.k-reference{font-size:12px;color:var(--muted)}
+  .src-chip{margin-left:auto;align-self:center;font-size:11px;border-radius:99px;padding:2px 9px;margin-bottom:4px;white-space:nowrap}
+  .src-chip.good{background:#e7f6ec;color:var(--green)}
+  .src-chip.ok{background:#eff6ff;color:#1d4ed8}
+  .src-chip.weak{background:#fde8e8;color:var(--red)}
+  .ev .pdf-tag{font-size:10px;font-weight:600;border-radius:4px;padding:0 4px;background:#eff6ff;color:#1d4ed8;cursor:pointer}
+  .ev .g-pdf{color:var(--accent);font-weight:600}
+  #seltool{position:fixed;display:none;z-index:40;background:var(--ink);color:#fff;border-radius:8px;padding:6px 10px;font-size:12px;box-shadow:0 4px 14px rgba(0,0,0,.25);cursor:pointer}
+  /* ---------- right ---------- */
+  .rt-help{font-size:12px;color:var(--muted);padding:8px 14px 0}
+  .recwrap{padding:10px 14px 80px}
+  .record{background:var(--panel);border:1px solid var(--line);border-radius:10px;margin-bottom:14px}
+  .rec-head{display:flex;align-items:center;gap:10px;padding:8px 12px;border-bottom:1px solid var(--line);background:#fbfcfe;border-radius:10px 10px 0 0;flex-wrap:wrap}
+  .rec-head .rlabel{font-weight:600;font-size:13px}
+  .rec-head .uid{font-size:11px;color:var(--muted)}
+  .extras{display:flex;gap:10px;align-items:center;flex-wrap:wrap;font-size:12px}
+  .extras select{width:auto}
+  .group{border-top:1px solid var(--line)}
+  .group:first-of-type{border-top:none}
+  .group-title{font-size:12px;font-weight:600;color:var(--muted);padding:8px 12px 0;cursor:pointer}
+  .group-title .tri{display:inline-block;transition:.15s}
+  .group.closed .tri{transform:rotate(-90deg)}
+  .group.closed .field{display:none}
+  /* ---------- field card ---------- */
+  .field{padding:8px 12px;border-top:1px dashed #eef1f6}
+  .field.active{background:var(--accent-soft);outline:2px solid var(--accent);outline-offset:-2px;border-radius:6px}
+  .field.na{background:var(--na);opacity:.65}
+  .f-head{display:flex;align-items:baseline;gap:8px;cursor:pointer}
+  .f-id{font-family:ui-monospace,monospace;font-size:12px;color:var(--blue);font-weight:600}
+  .f-label{font-size:13px}
+  .badge{font-size:10px;border-radius:4px;padding:1px 5px;font-weight:600}
+  .b-novel{background:#fdf2f8;color:#be185d}
+  .b-op{background:#eff6ff;color:#1d4ed8}
+  .b-gold{background:#fef9c3;color:#a16207}
+  .b-verb{background:#f0fdf4;color:#15803d}
+  .b-na{background:#e2e8f0;color:#475569}
+  .f-done{margin-left:auto;font-size:11px;color:var(--green)}
+  .f-body{margin-top:6px;display:grid;grid-template-columns:150px 170px 1fr;gap:6px;align-items:start}
+  .f-body .full{grid-column:1/-1}
+  .f-hint{grid-column:1/-1;font-size:11px;color:var(--muted)}
+  .ev-list{grid-column:1/-1;display:flex;flex-direction:column;gap:4px}
+  .ev{display:flex;gap:6px;align-items:center;background:#fbfcfe;border:1px solid var(--line);border-radius:6px;padding:4px 6px;font-size:12px}
+  .ev .q{flex:1;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;cursor:pointer}
+  .ev select{width:auto;font-size:11px;padding:2px 4px}
+  .ev .g-ok{color:var(--green)} .ev .g-bad{color:var(--red);font-weight:600}
+  .ev label{display:flex;gap:2px;align-items:center;font-size:11px;color:var(--muted);white-space:nowrap}
+  .axes-row{display:flex;gap:6px;margin-bottom:4px}
+  .axes-row input{width:140px}
+  .fk-box{border:1px solid var(--line);border-radius:6px;background:#fff;padding:4px 8px;max-height:110px;overflow:auto}
+  .fk-box label{display:flex;gap:6px;font-size:12px;align-items:center}
+  .addbar{padding:0 14px 20px}
+  .footer-tip{flex:none;background:var(--panel);border-top:1px solid var(--line);padding:5px 14px;font-size:11px;color:var(--muted)}
+</style>
+</head>
+<body>
+
+<div id="login">
+  <div class="box">
+    <h1>Reproducibility Annotator</h1>
+    <div class="sub">Blind mode · schema-driven · full audit trail. Do not consult any model output.</div>
+    <div id="step-login">
+      <div id="quick-ids" style="display:none">
+        <label>Who are you?</label>
+        <div id="quick-list" style="display:flex;gap:8px;flex-wrap:wrap"></div>
+        <label style="margin-top:16px">or type an ID</label>
+      </div>
+      <label id="id-label">Annotator ID (e.g. A / B, keep it consistent)</label>
+      <input type="text" id="in-annotator" placeholder="A" autocomplete="username">
+      <div id="pw-wrap" style="display:none">
+        <label>Password</label>
+        <input type="password" id="in-password" autocomplete="current-password">
+      </div>
+      <div class="login-err" id="login-err"></div>
+      <div style="margin-top:18px;text-align:right"><button class="primary" id="btn-login">Sign in</button></div>
+    </div>
+  </div>
+</div>
+
+<div id="home">
+  <div class="topbar">
+    <span class="brand">Reproducibility Annotator<small>independent double annotation</small></span>
+    <span class="chip" id="hm-schema"></span>
+    <span class="spacer"></span>
+    <button id="hm-add" class="primary" style="display:none">＋ Add paper</button>
+    <span id="hm-view" style="display:none;font-size:12px;color:var(--muted)">Viewing annotator <select id="hm-annotator"></select></span>
+    <span class="chip" id="hm-who"></span>
+    <button id="hm-logout">Sign out</button>
+  </div>
+  <div class="home-wrap">
+    <div class="home-head">
+      <h2>Papers</h2>
+      <span class="home-stats" id="hm-stats"></span>
+    </div>
+    <div class="blind-note" id="hm-note">Blind mode: you only see your own annotations. Open a card to preview the PDF and your annotation cards.</div>
+    <div class="filters">
+      <input type="text" id="hm-q" placeholder="Search title or ID">
+      <span id="hm-venues"></span>
+      <span style="width:8px"></span>
+      <span id="hm-status"></span>
+    </div>
+    <div class="grid" id="hm-grid"></div>
+  </div>
+</div>
+
+<div id="upload">
+  <div class="box">
+    <h3>Add a paper</h3>
+    <div class="sub">Upload a PDF, or just give a PMCID / DOI / PMID. If the paper is in the PMC open-access subset the publisher's XML is fetched automatically (best text); otherwise the PDF is converted with Docling. Conversion takes about 10 s – 2 min. Papers are only ever added, never overwritten.</div>
+    <label>PDF</label>
+    <input type="file" id="up-pdf" accept="application/pdf,.pdf">
+    <label>PMCID / DOI / PMID <span class="muted">(optional; detected from the PDF if left empty)</span></label>
+    <input type="text" id="up-ident" placeholder="e.g. PMC4502302 or 10.1155/2015/605940">
+    <div class="row">
+      <div><label>Title <span class="muted">(optional)</span></label><input type="text" id="up-title"></div>
+      <div style="max-width:160px"><label>Venue <span class="muted">(optional)</span></label><input type="text" id="up-venue" placeholder="e.g. MICCAI"></div>
+    </div>
+    <label style="display:flex;gap:6px;align-items:center;color:var(--ink);font-size:13px;margin-top:14px"><input type="checkbox" id="up-pool" checked> Add to the annotators' pool (everyone except admin sees only pool papers)</label>
+    <div class="acts"><button class="primary" id="up-go">Upload &amp; convert</button><button id="up-close">Close</button><span id="up-err"></span></div>
+    <div id="up-jobs"></div>
+  </div>
+</div>
+
+<div id="detail">
+  <div class="modal">
+    <div class="m-head">
+      <div style="min-width:0">
+        <div class="meta" id="dt-meta" style="display:flex;gap:8px;align-items:center;font-size:12px;color:var(--muted)"></div>
+        <h2 id="dt-title"></h2>
+      </div>
+      <button class="x" id="dt-close" title="Close (Esc)">×</button>
+    </div>
+    <div class="m-body">
+      <div class="m-pdf" id="dt-pdf"></div>
+      <div class="m-side">
+        <div class="m-cards" id="dt-cards"></div>
+        <div class="m-foot">
+          <span class="muted" id="dt-sum" style="font-size:12px"></span>
+          <span class="spacer"></span>
+          <a id="dt-pdflink" target="_blank" style="font-size:12px">Open PDF in new tab ↗</a>
+          <button class="primary" id="dt-start">Start annotating</button>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+
+<div id="app">
+  <header>
+    <span class="title" id="h-paper"></span>
+    <span class="chip" id="h-annotator"></span>
+    <span class="chip" id="h-schema"></span>
+    <span class="chip" id="h-progress">0 fields annotated</span>
+    <span class="spacer"></span>
+    <span class="chip sync" id="h-sync" title="Click to sync now">…</span>
+    <button id="btn-switch">← Papers</button>
+    <button id="btn-logout">Sign out</button>
+  </header>
+  <div id="main">
+    <div id="left">
+      <div class="tabs" id="lt-tabs"></div>
+      <div class="lpane"><div id="pdfview"></div><div id="textpane"></div></div>
+    </div>
+    <div id="splitter" title="Drag to resize"></div>
+    <div id="right">
+      <div class="tabs" id="rt-tabs"></div>
+      <div class="rt-help" id="rt-help"></div>
+      <div class="pane"><div class="recwrap" id="recwrap"></div></div>
+      <div class="footer-tip">Select text in the text pane <b>or on the PDF</b> → "Add as evidence" or ⌘/Ctrl+E attaches it to the active field · click a paragraph to see it on the PDF (and vice versa) · if text and PDF disagree, trust the PDF and tick dmg · ✓ grounded / ✗ mismatch · autosave</div>
+    </div>
+  </div>
+</div>
+
+<div id="seltool">Add as evidence ⌘E</div>
+
+<script>
+"use strict";
+const $=s=>document.querySelector(s), $$=s=>[...document.querySelectorAll(s)];
+const api=(p,opt)=>fetch(p,opt).then(r=>{
+  if(r.status===401&&S.annotator){alert("Session expired, please sign in again");location.reload();}
+  if(!r.ok)throw new Error(p+" "+r.status);return r.json()});
+const lsGet=()=>{try{return JSON.parse(localStorage.getItem("repl_ann")||"{}")}catch(e){return {}}};
+const lsSet=v=>{try{localStorage.setItem("repl_ann",JSON.stringify(v))}catch(e){}};
+
+const S={annotator:null,paper:null,schema:null,manifest:null,records:[],fields:{},rtype:null,active:null,rawText:"",saveTimers:{}};
+
+/* ---------------- boot / login ---------------- */
+(async function(){
+  const cfg=await fetch("/api/config").then(r=>r.json());
+  S.authMode=cfg.auth;
+  $("#pw-wrap").style.display=cfg.auth?"block":"none";
+  if(!cfg.auth&&cfg.annotators&&cfg.annotators.length){
+    $("#quick-ids").style.display="block";$("#id-label").style.display="none";
+    $("#quick-list").innerHTML=cfg.annotators.map(a=>`<button class="qid" data-id="${esc(a)}" style="padding:6px 16px;font-weight:600">${esc(a)}</button>`).join("");
+    $("#quick-list").onclick=e=>{const b=e.target.closest(".qid");if(b){$("#in-annotator").value=b.dataset.id;doLogin()}};
+  }
+  const saved=lsGet();
+  if(saved.annotator)$("#in-annotator").value=saved.annotator;
+  const me=await fetch("/api/me");
+  if(me.ok)await enterHome(await me.json());
+})();
+
+async function doLogin(){
+  const a=$("#in-annotator").value.trim(), pw=$("#in-password").value;
+  if(!a){$("#login-err").textContent="Enter an annotator ID";return}
+  const r=await fetch("/api/login",{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({annotator:a,password:pw})});
+  if(!r.ok){$("#login-err").textContent=r.status===401?(S.authMode?"Wrong ID or password":"Unknown annotator ID"):r.status===400?"ID: letters, digits, _ or - only":r.status===403?"This ID cannot sign in":"Login failed ("+r.status+")";return}
+  $("#login-err").textContent="";
+  await enterHome(await api("/api/me"));
+}
+$("#btn-login").onclick=doLogin;
+$("#in-password").addEventListener("keydown",e=>{if(e.key==="Enter")doLogin()});
+$("#in-annotator").addEventListener("keydown",e=>{if(e.key==="Enter"&&!S.authMode)doLogin()});
+
+/* ---------------- home: paper cards ---------------- */
+const enc=encodeURIComponent;
+const BLOCKS=[["l1","L1"],["dataset","D"],["split","S"],["asset","A"],["model","M"],["result","R"],["claim","C"]];
+/* All UI text is English (0925). Schema labels carry Chinese in parentheses; stripped for display (schema file untouched). */
+const EN_RT={l1:"L1 characterization",dataset:"Datasets",split:"Splits",asset:"Artifacts (code / weights / environment)",model:"Models",result:"Results",claim:"Claims"};
+const EN_STATUS={stated:"stated",inferred:"inferred",not_reported:"not reported",absent_deferred:"deferred elsewhere",uncertain:"uncertain"};
+const prettyEnum=t=>String(t).replace(/^C\d_/,"").replace(/_/g," ");
+const stripZh=t=>typeof t==="string"?t.replace(/\s*[（(](?=[^()（）]*[\u4e00-\u9fff])[^()（）]*[)）]/g,"").trim():t;
+function enSchema(x){if(Array.isArray(x))return x.map(enSchema);if(x&&typeof x==="object"){const o={};for(const [k,v] of Object.entries(x))o[k]=(k==="label"||k==="title"||k==="help"||k==="hint")?stripZh(v):enSchema(v);return o}return x}
+const H={view:null,overview:{},q:"",venue:"all",status:"all",pid:null};
+const rtDef=id=>S.schema.record_types.find(r=>r.id===id);
+const fieldDefs=rt=>rt.fields||(rt.groups||[]).flatMap(g=>g.fields||[]);
+const isFilled=p=>!!(p&&(p.status||p.value||(p.evidence&&p.evidence.length)||(p.fk&&p.fk.length)||(p.axes&&p.axes.length)||p.no_anchor));
+function valOf(p,max=90){
+  if(!p)return "";
+  let v=p.value;
+  if(v&&typeof v==="object")v=Array.isArray(v)?v.join(", "):Object.values(v).filter(Boolean).join(" · ");
+  v=(v||"").toString().trim();
+  if(!v&&p.status)v="("+(EN_STATUS[p.status]||p.status)+")";
+  return v.length>max?v.slice(0,max)+"…":v;
+}
+
+async function enterHome(me){
+  S.me=me;
+  if(!S.schema)S.schema=enSchema(await api("/api/schema"));
+  if(!S.manifest)S.manifest=await api("/api/papers");
+  H.view=H.view||me.annotator;
+  $("#hm-schema").textContent="schema "+S.schema.schema_version;
+  $("#hm-who").textContent="Signed in: "+me.annotator+(me.admin?" (admin)":"");
+  if(me.admin){
+    $("#hm-view").style.display="inline";$("#hm-add").style.display="inline-block";
+    $("#hm-annotator").innerHTML=me.annotators.map(a=>`<option value="${esc(a)}" ${a===H.view?"selected":""}>${esc(a)}</option>`).join("");
+    $("#hm-note").textContent="Admin view: switch annotator at the top right to read anyone's cards (read-only). Annotators only ever see their own.";
+  }
+  const venues=[...new Set(Object.values(S.manifest.papers).map(e=>e.venue).filter(Boolean))].sort();
+  $("#hm-venues").innerHTML=["all",...venues].map(v=>`<span class="pill ${v===H.venue?"on":""}" data-venue="${esc(v)}">${v==="all"?"All venues":esc(v)}</span>`).join(" ");
+  $("#hm-status").innerHTML=[["all","Any status"],["todo","Not started"],["doing","In progress"]].map(([k,l])=>`<span class="pill ${k===H.status?"on":""}" data-status="${k}">${l}</span>`).join(" ");
+  $("#login").style.display="none";$("#app").style.display="none";$("#home").style.display="block";
+  await loadOverview();
+}
+async function loadOverview(){
+  $("#hm-grid").innerHTML=`<div class="empty">Loading…</div>`;
+  H.overview=(await api(`/api/overview?annotator=${enc(H.view)}`)).papers;
+  renderGrid();
+}
+const statusOf=pid=>(H.overview[pid]&&H.overview[pid].filled>0)?"doing":"todo";
+function renderGrid(){
+  const all=Object.entries(S.manifest.papers);
+  const doing=all.filter(([p])=>statusOf(p)==="doing").length;
+  $("#hm-stats").textContent=`${all.length} papers · ${doing} in progress · ${all.length-doing} not started`+(H.view!==S.me.annotator?` · viewing ${H.view}`:"");
+  const q=H.q.toLowerCase();
+  const rows=all.filter(([pid,e])=>(H.venue==="all"||e.venue===H.venue)&&(H.status==="all"||statusOf(pid)===H.status)
+    &&(!q||pid.toLowerCase().includes(q)||(e.title||"").toLowerCase().includes(q)));
+  if(!rows.length){$("#hm-grid").innerHTML=`<div class="empty">No papers match</div>`;return}
+  $("#hm-grid").innerHTML=rows.map(([pid,e])=>{
+    const o=H.overview[pid]||{blocks:{},filled:0};
+    const blocks=BLOCKS.map(([id,sh])=>{
+      const b=o.blocks[id]||{records:0,filled:0},rt=rtDef(id);
+      const on=b.filled>0;
+      return `<span class="blk ${on?"on":""}" style="${on?`background:var(--c-${id})`:""}" title="${esc(EN_RT[id]||id)}: ${b.records} records · ${b.filled} fields filled">${sh}</span>`;
+    }).join("");
+    const st=statusOf(pid);
+    return `<div class="pcard" data-pid="${esc(pid)}">
+      <div class="meta"><span class="venue">${esc(e.venue||"")}</span><span>${esc(pid)}</span>${e.text_source==="jats"?'<span class="src-tag">PMC XML</span>':""}${S.me.admin&&S.manifest.pool?`<span style="flex:1"></span><span class="pool-pill ${S.manifest.pool.includes(pid)?"on":""}" data-pool="${esc(pid)}" title="Whether annotators (A/B/C…) see this paper">${S.manifest.pool.includes(pid)?"✓ in pool":"not in pool"}</span>`:""}</div>
+      <h3>${esc(e.title||pid)}</h3>
+      <div class="abs">${esc(e.abstract||"")}</div>
+      <div class="foot"><div class="blocks">${blocks}</div>
+        <span class="status ${st}">${st==="doing"?o.filled+" fields":"Not started"}</span></div>
+    </div>`;
+  }).join("");
+}
+$("#hm-grid").onclick=async e=>{
+  const pp=e.target.closest(".pool-pill");
+  if(pp){
+    e.stopPropagation();const pid=pp.dataset.pool,inc=!S.manifest.pool.includes(pid);
+    pp.textContent="…";
+    try{const r=await api("/api/admin/pool",{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({paper:pid,include:inc})});S.manifest.pool=r.pool}
+    catch(err){alert("Could not update the pool: "+err.message)}
+    renderGrid();return;
+  }
+  const c=e.target.closest(".pcard");if(c)openDetail(c.dataset.pid)};
+
+/* ---------------- admin: add paper (1003) ---------------- */
+const UP={timer:null};
+$("#hm-add").onclick=()=>{$("#upload").style.display="flex";$("#up-err").textContent="";pollJobs()};
+$("#up-close").onclick=()=>{$("#upload").style.display="none"};
+$("#upload").onclick=e=>{if(e.target.id==="upload")$("#upload").style.display="none"};
+$("#up-go").onclick=async()=>{
+  const f=$("#up-pdf").files[0],ident=$("#up-ident").value.trim();
+  if(!f&&!ident){$("#up-err").textContent="Choose a PDF or enter an ID";return}
+  const fd=new FormData();
+  if(f)fd.append("pdf",f);
+  fd.append("ident",ident);fd.append("title",$("#up-title").value.trim());fd.append("venue",$("#up-venue").value.trim());
+  fd.append("add_to_pool",$("#up-pool").checked?"true":"false");
+  $("#up-go").disabled=true;$("#up-err").textContent="Uploading…";
+  try{
+    const r=await fetch("/api/admin/upload",{method:"POST",body:fd});
+    if(!r.ok){const t=await r.json().catch(()=>({}));throw new Error(t.detail||r.status)}
+    $("#up-err").textContent="";$("#up-pdf").value="";$("#up-ident").value="";$("#up-title").value="";$("#up-venue").value="";
+  }catch(err){$("#up-err").textContent=String(err.message||err)}
+  $("#up-go").disabled=false;pollJobs();
+};
+async function pollJobs(){
+  clearTimeout(UP.timer);
+  let jobs=[];try{jobs=(await api("/api/admin/jobs")).jobs}catch(e){return}
+  const ST={queued:"waiting",running:"converting…",done:"added",error:"failed"};
+  $("#up-jobs").innerHTML=jobs.map(j=>`<div class="job"><span class="st ${j.status}">${ST[j.status]||j.status}</span> · ${esc(j.file||j.ident||"")}${j.pid?` → <b>${esc(j.pid)}</b>`:""}${j.error?`<div style="color:var(--red);margin-top:4px">${esc(j.error)}</div>`:""}<pre>${esc((j.log||[]).join("\n"))}</pre></div>`).join("");
+  const busy=jobs.some(j=>j.status==="queued"||j.status==="running");
+  const fresh=jobs.filter(j=>j.status==="done"&&!(j.pid in S.manifest.papers));
+  if(fresh.length){S.manifest=await api("/api/papers");await loadOverview()}
+  if(busy||$("#upload").style.display==="flex")UP.timer=setTimeout(pollJobs,busy?2000:6000);
+}
+$("#hm-q").oninput=e=>{H.q=e.target.value;renderGrid()};
+$("#hm-venues").onclick=e=>{const p=e.target.closest(".pill");if(!p)return;H.venue=p.dataset.venue;$$("#hm-venues .pill").forEach(x=>x.classList.toggle("on",x===p));renderGrid()};
+$("#hm-status").onclick=e=>{const p=e.target.closest(".pill");if(!p)return;H.status=p.dataset.status;$$("#hm-status .pill").forEach(x=>x.classList.toggle("on",x===p));renderGrid()};
+$("#hm-annotator").onchange=e=>{H.view=e.target.value;loadOverview()};
+
+/* ---------------- detail: PDF preview + annotation cards ---------------- */
+async function openDetail(pid){
+  H.pid=pid;const e=S.manifest.papers[pid];
+  $("#dt-meta").innerHTML=`<span class="venue">${esc(e.venue||"")}</span><span>${esc(pid)}</span>`;
+  $("#dt-title").textContent=e.title||pid;
+  const url=`/api/paper/${enc(pid)}/pdf`;
+  $("#dt-pdf").innerHTML=e.pdf?`<iframe src="${url}#navpanes=0&view=FitH"></iframe>`:`<div class="nopdf">No PDF for this paper</div>`;
+  $("#dt-pdflink").style.display=e.pdf?"inline":"none";$("#dt-pdflink").href=url;
+  $("#dt-cards").innerHTML=`<div class="muted">Loading…</div>`;
+  $("#detail").style.display="flex";
+  const st=await api(`/api/state?paper=${enc(pid)}&annotator=${enc(H.view)}`);
+  if(H.pid!==pid)return;
+  renderCards(st);
+  const mine=!st.read_only, started=Object.values(st.fields).some(m=>Object.values(m).some(isFilled));
+  $("#dt-start").textContent=!mine?`Annotate as ${S.me.annotator}`:started?"Continue annotating":"Start annotating";
+}
+function recordLine(rt,r,flds){
+  const f=flds||{},x=r.extra||{};
+  const tags=Object.entries(x).filter(([k,v])=>v&&k!=="model_fk"&&typeof v!=="object").map(([k,v])=>{const t=v===true?k:String(v);return `<span class="tag">${esc(prettyEnum(t))}</span>`}).join("");
+  let main;
+  if(rt.id==="result"){main=[valOf(f.R1,50),valOf(f.R2,40)].filter(Boolean).join(" = ")}
+  else if(rt.id==="claim"){main=valOf(f.F1,160)}
+  else if(rt.id==="asset"){main=[x.asset_type&&prettyEnum(x.asset_type),valOf(f.availability_claim,90)].filter(Boolean).join(": ")}
+  else{main=valOf(f[rt.label_field],80)}
+  const extra=rt.id==="dataset"&&f.D3?`<span class="k">source</span>${esc(valOf(f.D3,40))}`:rt.id==="split"&&f.D26?`<span class="k">split unit</span>${esc(valOf(f.D26,40))}`:"";
+  const n=fieldDefs(rt).filter(d=>isFilled(f[d.id])).length;
+  return `<li>${main?esc(main):`<span class="none">(unnamed)</span>`}${rt.id==="asset"?"":tags} ${extra?"<br>"+extra:""}<span class="tag" style="float:right">${n}/${fieldDefs(rt).length}</span></li>`;
+}
+function renderCards(st){
+  const by={};st.records.forEach(r=>(by[r.rtype]=by[r.rtype]||[]).push(r));
+  let totalFilled=0;
+  $("#dt-cards").innerHTML=S.schema.record_types.map(rt=>{
+    const defs=fieldDefs(rt),recs=by[rt.id]||[];
+    const filledN=recs.reduce((s,r)=>s+defs.filter(d=>isFilled((st.fields[r.uid]||{})[d.id])).length,0);
+    totalFilled+=filledN;
+    const denom=defs.length*Math.max(recs.length,1),pct=Math.round(100*filledN/denom);
+    let body;
+    if(rt.cardinality==="single"){
+      const r=recs[0],f=r?(st.fields[r.uid]||{}):{};
+      const items=defs.filter(d=>d.type!=="gate_list").map(d=>`<li><span class="k">${esc(d.label)}</span>${isFilled(f[d.id])?esc(valOf(f[d.id],70)):'<span class="none">—</span>'}</li>`);
+      body=`<ul>${items.join("")}</ul>`;
+    }else{
+      body=recs.length?`<ul>${recs.map(r=>recordLine(rt,r,st.fields[r.uid])).join("")}</ul>`:`<div class="none">Not annotated yet</div>`;
+    }
+    const sub=rt.cardinality==="single"?`${filledN}/${defs.length} fields`:`${recs.length} record${recs.length===1?"":"s"} · ${filledN} fields filled`;
+    return `<div class="bcard ${rt.cardinality==="single"||rt.id==="claim"?"wide":""}" style="--bc:var(--c-${rt.id})">
+      <h4>${esc(EN_RT[rt.id]||rt.label)}</h4><div class="sub">${sub}</div>
+      <div class="bar"><i style="width:${Math.min(pct,100)}%"></i></div>${body}</div>`;
+  }).join("");
+  $("#dt-sum").textContent=(st.read_only?`${st.annotator}'s annotation (read-only) · `:"")+`${totalFilled} fields filled in total`;
+}
+function closeDetail(){$("#detail").style.display="none";$("#dt-pdf").innerHTML="";H.pid=null}
+$("#dt-close").onclick=closeDetail;
+$("#detail").onclick=e=>{if(e.target.id==="detail")closeDetail()};
+document.addEventListener("keydown",e=>{if(e.key==="Escape"&&$("#detail").style.display==="flex")closeDetail()});
+$("#dt-start").onclick=async()=>{
+  const pid=H.pid;closeDetail();
+  S.annotator=S.me.annotator;S.paper=pid;
+  lsSet({annotator:S.annotator,paper:pid});
+  $("#home").style.display="none";
+  await loadPaper();
+  $("#app").style.display="flex";
+  pollSync();if(!S.syncTimer)S.syncTimer=setInterval(pollSync,5000);
+};
+
+async function logout(){
+  await flushPendingSaves();
+  await fetch("/api/sync",{method:"POST"}).catch(()=>{});
+  await fetch("/api/logout",{method:"POST"});location.reload();
+}
+$("#btn-logout").onclick=logout;
+$("#hm-logout").onclick=logout;
+$("#btn-switch").onclick=async()=>{
+  await flushPendingSaves();
+  $("#app").style.display="none";$("#home").style.display="block";
+  H.view=S.me.annotator;if(S.me.admin)$("#hm-annotator").value=H.view;
+  await loadOverview();
+};
+
+/* ---------------- sync indicator ---------------- */
+function fmtTime(ts){return new Date(ts*1000).toLocaleTimeString([], {hour:"2-digit",minute:"2-digit",second:"2-digit"})}
+function showSync(s){
+  const el=$("#h-sync");el.classList.remove("ok","pending","err");
+  const where=s.backend==="github"?"GitHub":"disk";
+  if(s.error){el.classList.add("err");el.textContent="Sync error, retrying";el.title=s.error;return}
+  if(s.pending||Object.keys(S.saveTimers).length){el.classList.add("pending");el.textContent="Saving…";el.title="Changes are saved on the server and will be committed to "+where+" within "+s.flush_seconds+"s";return}
+  el.classList.add("ok");el.textContent=s.last_ok?"Synced to "+where+" ✓ "+fmtTime(s.last_ok):"Synced ✓";el.title="Click to sync now";
+}
+async function pollSync(){try{showSync(await api("/api/sync"))}catch(e){}}
+$("#h-sync").onclick=async()=>{try{showSync(await api("/api/sync",{method:"POST"}))}catch(e){}};
+async function flushPendingSaves(){
+  for(const [k,t] of Object.entries(S.saveTimers)){clearTimeout(t);const f=S.pendingSaves&&S.pendingSaves[k];if(f)await f();}
+  S.saveTimers={};
+}
+window.addEventListener("beforeunload",e=>{if(Object.keys(S.saveTimers).length){e.preventDefault();e.returnValue=""}});
+
+async function loadPaper(){
+  const pe=enc(S.paper), entry=S.manifest.papers[S.paper];
+  const [text,state,layout]=await Promise.all([
+    fetch(`/api/paper/${pe}/text`).then(r=>r.text()),
+    api(`/api/state?paper=${pe}`),
+    fetch(`/api/paper/${pe}/layout`).then(r=>r.ok?r.json():null).catch(()=>null)
+  ]);
+  S.rawText=text;S.records=state.records;S.fields=state.fields;S.layout=layout;
+  S.isMd=(entry.fulltext||"").endsWith(".md");S.rawView=false;
+  $("#h-paper").textContent=S.paper;
+  $("#h-annotator").textContent="Annotator "+S.annotator;
+  $("#h-schema").textContent="schema "+S.schema.schema_version;
+  setupLeftTabs(entry);
+  openPdf(entry.pdf?`/api/paper/${pe}/pdf`:null);
+  S.rtype=S.schema.record_types[0].id;
+  ensureSingletons();
+  renderTabs();renderRight();updateProgress();
+}
+
+async function ensureSingletons(){
+  for(const rt of S.schema.record_types.filter(r=>r.cardinality==="single")){
+    if(!S.records.some(r=>r.rtype===rt.id)){
+      const res=await api("/api/record",{method:"POST",headers:{"Content-Type":"application/json"},
+        body:JSON.stringify({annotator:S.annotator,paper:S.paper,action:"create",rtype:rt.id,extra:{}})});
+      S.records.push({uid:res.uid,rtype:rt.id,extra:{}});
+    }
+  }
+  renderTabs();renderRight();
+}
+
+/* ---------------- left pane ---------------- */
+function esc(t){return t.replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;")}
+function renderText(hlFrom,hlTo){
+  const el=$("#textpane");
+  el.classList.toggle("linked",!!S.layout&&!S.rawView);
+  if(S.layout&&!S.rawView){
+    /* 1003: 按 layout 块渲染, 每块记 data-b, 用来和 PDF 互相定位 */
+    el.innerHTML=S.layout.blocks.map(b=>`<div class="tb k-${b.kind}" data-b="${b.id}">${mdToHtml(S.rawText.slice(b.start,b.end))}</div>`).join("");
+    return;
+  }
+  if(S.isMd&&!S.rawView){el.innerHTML=mdToHtml(S.rawText);return}
+  if(hlFrom==null){el.innerHTML=esc(S.rawText);return}
+  el.innerHTML=esc(S.rawText.slice(0,hlFrom))+"<mark id='hl'>"+esc(S.rawText.slice(hlFrom,hlTo))+"</mark>"+esc(S.rawText.slice(hlTo));
+  document.getElementById("hl")?.scrollIntoView({block:"center",behavior:"smooth"});
+}
+/* 极简 md 渲染: 标题 / 管道表格 / 去粗斜体标记。只做展示, 取证坐标由后端宽容匹配回源文件 */
+function mdToHtml(src){
+  const inline=t=>esc(t).replace(/\*\*([^*]+)\*\*/g,"$1").replace(/\*([^*]+)\*/g,"$1").replace(/`([^`]+)`/g,"$1");
+  const lines=src.split("\n");
+  let html="",i=0,para=[];
+  const flush=()=>{if(para.length){html+="<p>"+inline(para.join(" "))+"</p>";para=[]}};
+  while(i<lines.length){
+    const L=lines[i];
+    if(/^\s*\|/.test(L)){
+      flush();
+      const rows=[];
+      while(i<lines.length&&/^\s*\|/.test(lines[i])){
+        if(!/^\s*\|[\s\-:|]+\|?\s*$/.test(lines[i]))rows.push(lines[i]);
+        i++;
+      }
+      html+="<table>"+rows.map((r,ri)=>{
+        const cells=r.replace(/^\s*\|/,"").replace(/\|\s*$/,"").split(/(?<!\\)\|/).map(c=>c.replace(/\\\|/g,"|"));
+        const tag=ri===0?"th":"td";
+        return "<tr>"+cells.map(c=>`<${tag}>`+inline(c.trim())+`</${tag}>`).join("")+"</tr>";
+      }).join("")+"</table>";
+      continue;
+    }
+    const h=L.match(/^(#{1,6})\s+(.*)/);
+    if(h){flush();const lv=Math.min(h[1].length+1,6);html+=`<h${lv}>`+inline(h[2])+`</h${lv}>`;i++;continue}
+    if(/^\s*<!--.*-->\s*$/.test(L)){i++;continue}
+    if(/^\s*$/.test(L)){flush();i++;continue}
+    para.push(L);i++;
+  }
+  flush();
+  return html;
+}
+/* ---------------- left: views (side by side / text / PDF / raw) ---------------- */
+const SRC={jats:["good","Text: publisher XML (official)","Text comes from the PMC XML, not from PDF conversion"],
+  docling:["ok","Text: layout-aware PDF conversion","Converted with Docling; tables/formulas can still be wrong, check against the PDF"],
+  docling_0817:["ok","Text: PDF conversion (0817)","Docling conversion without PDF linking"],
+  pymupdf:["weak","Text: plain PDF extraction","Flat PyMuPDF text: tables are often scrambled, check against the PDF"]};
+const W=(()=>{try{return Object.assign({split:64,single:46},JSON.parse(localStorage.getItem("repl_widths")||"{}"))}catch(e){return {split:64,single:46}}})();
+function saveW(){try{localStorage.setItem("repl_widths",JSON.stringify(W))}catch(e){}}
+function applyLeftWidth(){$("#left").style.width=(S.view==="split"?W.split:W.single)+"%"}
+function setupLeftTabs(entry){
+  const views=S.layout?[["split","Side by side"],["text","Text"],["pdf","PDF"]]:[["text","Text"],["pdf","PDF"]];
+  if(S.isMd)views.push(["raw","Raw MD"]);
+  const src=SRC[entry.text_source||(S.isMd?"docling_0817":"pymupdf")]||SRC.pymupdf;
+  $("#lt-tabs").innerHTML=views.map(([k,l])=>`<div class="tab" data-lt="${k}">${l}</div>`).join("")+`<span class="src-chip ${src[0]}" title="${esc(src[2])}">${esc(src[1])}</span>`;
+  $$("#lt-tabs .tab").forEach(t=>t.onclick=()=>setView(t.dataset.lt));
+  setView(S.layout?"split":"text");
+}
+function setView(v){
+  S.view=v;S.rawView=(v==="raw");
+  $$("#lt-tabs .tab").forEach(x=>x.classList.toggle("on",x.dataset.lt===v));
+  $("#pdfview").style.display=(v==="split"||v==="pdf")?"block":"none";
+  $("#textpane").style.display=v==="pdf"?"none":"block";
+  applyLeftWidth();
+  if(v!=="pdf")renderText();
+}
+$("#splitter").onmousedown=e=>{
+  e.preventDefault();
+  const box=$("#main").getBoundingClientRect(),sp=$("#splitter");sp.classList.add("drag");
+  const key=S.view==="split"?"split":"single";
+  const mv=ev=>{W[key]=Math.min(82,Math.max(22,(ev.clientX-box.left)/box.width*100));$("#left").style.width=W[key]+"%"};
+  const up=()=>{document.removeEventListener("mousemove",mv);document.removeEventListener("mouseup",up);sp.classList.remove("drag");saveW()};
+  document.addEventListener("mousemove",mv);document.addEventListener("mouseup",up);
+};
+
+/* ---------------- PDF viewer (PDF.js, lazy per page; falls back to the browser viewer) ---------------- */
+if(window.pdfjsLib)pdfjsLib.GlobalWorkerOptions.workerSrc="https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.worker.min.js";
+const PV={doc:null,pages:[],width:0,hl:{},obs:null,token:0};
+async function openPdf(url){
+  const box=$("#pdfview"),my=++PV.token;
+  box.innerHTML="";PV.doc=null;PV.pages=[];PV.hl={};PV.width=0;
+  if(!url){box.innerHTML=`<div class="nopdf">No PDF for this paper</div>`;return}
+  if(!window.pdfjsLib){box.style.padding="0";box.innerHTML=`<iframe src="${url}" style="width:100%;height:100%;border:0"></iframe>`;return}
+  box.style.padding="";
+  try{
+    const doc=await pdfjsLib.getDocument({url}).promise;
+    if(my!==PV.token)return;
+    for(let n=1;n<=doc.numPages;n++){const page=await doc.getPage(n);if(my!==PV.token)return;PV.pages[n]={page}}
+    PV.doc=doc;layoutPages();
+  }catch(e){box.innerHTML=`<div class="nopdf">Could not load the PDF (${esc(String(e.message||e))})</div>`}
+}
+function layoutPages(){
+  const box=$("#pdfview");if(!PV.doc)return;
+  const w=box.clientWidth-24;if(w<60)return;          // hidden (text-only view)
+  const keep=PV.width?currentPdfSpot():null;
+  PV.width=w;
+  if(PV.obs)PV.obs.disconnect();
+  PV.obs=new IntersectionObserver(es=>es.forEach(e=>{if(e.isIntersecting)renderPage(+e.target.dataset.page)}),{root:box,rootMargin:"800px 0px"});
+  box.innerHTML="";
+  PV.pages.forEach((P,n)=>{
+    const vp=P.page.getViewport({scale:1});P.w=vp.width;P.scale=w/vp.width;P.rendered=false;
+    const d=document.createElement("div");d.className="pg";d.dataset.page=n;
+    d.style.width=w+"px";d.style.height=vp.height*P.scale+"px";
+    P.div=d;box.appendChild(d);PV.obs.observe(d);
+  });
+  if(keep)scrollPdfTo(keep.page,keep.y,false);
+}
+async function renderPage(n){
+  const P=PV.pages[n];if(!P||P.rendered)return;P.rendered=true;
+  const div=P.div,vp=P.page.getViewport({scale:P.scale}),dpr=window.devicePixelRatio||1;
+  const c=document.createElement("canvas");c.width=Math.floor(vp.width*dpr);c.height=Math.floor(vp.height*dpr);
+  c.style.width=vp.width+"px";c.style.height=vp.height+"px";div.appendChild(c);
+  await P.page.render({canvasContext:c.getContext("2d"),viewport:vp,transform:dpr!==1?[dpr,0,0,dpr,0,0]:undefined}).promise;
+  if(P.div!==div)return;                               // re-laid out meanwhile
+  div.style.setProperty("--scale-factor",P.scale);
+  const tl=document.createElement("div");tl.className="textLayer";div.appendChild(tl);
+  try{await pdfjsLib.renderTextLayer({textContentSource:P.page.streamTextContent(),container:tl,viewport:vp}).promise}catch(e){}
+  const hl=document.createElement("div");hl.className="hl-layer";div.appendChild(hl);
+  drawHl(n);
+}
+/* layout bbox = PDF points, top-left origin; PDF.js page width in points → css px */
+function pageScale(n){const P=PV.pages[n];if(!P)return 1;const lp=S.layout&&S.layout.pages&&S.layout.pages[n];return PV.width/(lp?lp[0]:P.w)}
+function currentPdfSpot(){
+  const box=$("#pdfview"),top=box.scrollTop;
+  for(const [n,P] of PV.pages.entries())if(P&&P.div&&P.div.offsetTop+P.div.offsetHeight>top)return {page:n,y:Math.max(0,top-P.div.offsetTop)/pageScale(n)};
+  return null;
+}
+function scrollPdfTo(n,y,smooth){
+  const P=PV.pages[n];if(!P||!P.div)return;
+  $("#pdfview").scrollTo({top:P.div.offsetTop+y*pageScale(n)-60,behavior:smooth?"smooth":"auto"});
+}
+function setHl(boxes,cls,scroll=true){
+  PV.hl={};(boxes||[]).forEach(b=>(PV.hl[b.page]=PV.hl[b.page]||[]).push({bbox:b.bbox,cls}));
+  PV.pages.forEach((P,n)=>{if(P&&P.rendered)drawHl(n)});
+  if(scroll&&boxes&&boxes.length&&$("#pdfview").style.display!=="none")scrollPdfTo(boxes[0].page,boxes[0].bbox[1],true);
+}
+function drawHl(n){
+  const P=PV.pages[n],layer=P&&P.div&&P.div.querySelector(".hl-layer");if(!layer)return;
+  const k=pageScale(n);
+  layer.innerHTML=(PV.hl[n]||[]).map(h=>{const [x0,y0,x1,y1]=h.bbox;
+    return `<i class="${h.cls}" style="left:${x0*k-2}px;top:${y0*k-2}px;width:${(x1-x0)*k+4}px;height:${(y1-y0)*k+4}px"></i>`}).join("");
+}
+let roT;new ResizeObserver(()=>{clearTimeout(roT);roT=setTimeout(()=>{
+  const w=$("#pdfview").clientWidth-24;if(PV.doc&&w>=60&&Math.abs(w-PV.width)>8)layoutPages()},150)}).observe($("#pdfview"));
+
+/* ---------------- text ↔ PDF linking ---------------- */
+function focusBlock(id,from){
+  const b=S.layout&&S.layout.blocks[id];if(!b)return;
+  $$("#textpane .tb.cur").forEach(x=>x.classList.remove("cur"));
+  const el=$(`#textpane .tb[data-b="${id}"]`);
+  if(el){el.classList.add("cur");if(from==="pdf")el.scrollIntoView({block:"center",behavior:"smooth"})}
+  setHl(b.boxes,"blk",from!=="pdf");
+}
+$("#textpane").addEventListener("click",e=>{
+  if(!S.layout||S.rawView||!window.getSelection().isCollapsed)return;
+  const tb=e.target.closest(".tb");if(tb)focusBlock(+tb.dataset.b,"text");
+});
+$("#pdfview").addEventListener("click",e=>{
+  if(!S.layout||!window.getSelection().isCollapsed)return;
+  const pg=e.target.closest(".pg");if(!pg)return;
+  const n=+pg.dataset.page,r=pg.getBoundingClientRect(),k=pageScale(n),x=(e.clientX-r.left)/k,y=(e.clientY-r.top)/k;
+  let best=null,area=Infinity;
+  for(const b of S.layout.blocks)for(const bx of b.boxes){
+    if(bx.page!==n)continue;const [x0,y0,x1,y1]=bx.bbox;
+    if(x>=x0-3&&x<=x1+3&&y>=y0-3&&y<=y1+3){const a=(x1-x0)*(y1-y0);if(a<area){area=a;best=b}}
+  }
+  if(best)focusBlock(best.id,"pdf");
+});
+/* PDF selection → page boxes (PDF points), merged per line */
+function selectionBoxes(range){
+  const pages=$$("#pdfview .pg").map(d=>[d,d.getBoundingClientRect()]),out=[];
+  for(const r of range.getClientRects()){
+    if(r.width<1||r.height<1)continue;
+    const hit=pages.find(([,b])=>r.top>=b.top-2&&r.bottom<=b.bottom+2&&r.left>=b.left-2&&r.right<=b.right+2);if(!hit)continue;
+    const [d,b]=hit,n=+d.dataset.page,k=pageScale(n);
+    const bb=[(r.left-b.left)/k,(r.top-b.top)/k,(r.right-b.left)/k,(r.bottom-b.top)/k];
+    const prev=out[out.length-1];
+    if(prev&&prev.page===n&&Math.abs(prev.bbox[1]-bb[1])<4&&bb[0]-prev.bbox[2]<30){
+      prev.bbox=[Math.min(prev.bbox[0],bb[0]),Math.min(prev.bbox[1],bb[1]),Math.max(prev.bbox[2],bb[2]),Math.max(prev.bbox[3],bb[3])];
+    }else out.push({page:n,bbox:bb});
+  }
+  return out.slice(0,60).map(o=>({page:o.page,bbox:o.bbox.map(v=>Math.round(v*10)/10)}));
+}
+
+/* selection toolbar */
+const seltool=$("#seltool");
+document.addEventListener("selectionchange",()=>{
+  const sel=window.getSelection();
+  if(sel.isCollapsed||!($("#textpane").contains(sel.anchorNode)||$("#pdfview").contains(sel.anchorNode))){seltool.style.display="none";return}
+  const r=sel.getRangeAt(0).getBoundingClientRect();
+  seltool.style.left=Math.min(r.left,innerWidth-160)+"px";
+  seltool.style.top=Math.max(4,r.top-34)+"px";
+  seltool.style.display="block";
+});
+seltool.onmousedown=e=>{e.preventDefault();addSelectionAsEvidence()};
+document.addEventListener("keydown",e=>{
+  if((e.metaKey||e.ctrlKey)&&e.key.toLowerCase()==="e"){e.preventDefault();addSelectionAsEvidence()}
+});
+function addSelectionAsEvidence(){
+  const sel=window.getSelection();
+  if(sel.isCollapsed||!sel.rangeCount)return;
+  const fromPdf=$("#pdfview").contains(sel.anchorNode);
+  let q=sel.toString();
+  if(fromPdf)q=q.replace(/([A-Za-z])-\s*\n\s*([a-z])/g,"$1$2");   // PDF line-break hyphenation
+  q=q.replace(/\s+/g," ").trim();
+  if(!q)return;
+  if(!S.active){alert("Activate a field card first");return}
+  const pl=getPayload(S.active.uid,S.active.fid);
+  pl.evidence=pl.evidence||[];
+  const ev={quote:q,section:"other",flags:{},grounded:null,char_span:null};
+  /* 在 PDF 上划选: 记下精确位置; 转换文本里对不上(损坏)时位置也不丢 */
+  if(fromPdf){ev.origin="pdf";ev.pdf_anchor={blocks:[],boxes:selectionBoxes(sel.getRangeAt(0))}}
+  pl.evidence.push(ev);
+  if(!pl.status)pl.status="stated";
+  saveField(S.active.uid,S.active.fid,pl,true);
+  sel.removeAllRanges();seltool.style.display="none";
+}
+
+/* ---------------- right pane ---------------- */
+function rt(){return S.schema.record_types.find(r=>r.id===S.rtype)}
+function recsOf(t){return S.records.filter(r=>r.rtype===t)}
+function getPayload(uid,fid){
+  S.fields[uid]=S.fields[uid]||{};
+  S.fields[uid][fid]=S.fields[uid][fid]||{value:"",status:"",granularity:"",evidence:[],defer_target:"",note:""};
+  return S.fields[uid][fid];
+}
+function naSet(){
+  const l1=recsOf("l1")[0];if(!l1)return new Set();
+  const v=(S.fields[l1.uid]?.L1_na_fields?.value)||"";
+  return new Set(v.split(/[,，\s]+/).map(x=>x.trim().toUpperCase()).filter(Boolean));
+}
+function recLabel(rec,def){
+  const lf=def.label_field;
+  if(lf&&def.extras?.some(e=>e.id===lf))return rec.extra[lf]||"(unset)";
+  if(lf)return (S.fields[rec.uid]?.[lf]?.value||"").slice(0,60)||"("+lf+" empty)";
+  return def.label;
+}
+
+function renderTabs(){
+  const bar=$("#rt-tabs");bar.innerHTML="";
+  S.schema.record_types.forEach(def=>{
+    const t=document.createElement("div");
+    t.className="tab"+(def.id===S.rtype?" on":"");
+    const n=recsOf(def.id).length;
+    t.innerHTML=esc(def.label)+(def.cardinality==="multi"?` <span class="cnt">(${n})</span>`:"");
+    t.onclick=()=>{S.rtype=def.id;renderTabs();renderRight()};
+    bar.appendChild(t);
+  });
+}
+
+function renderRight(){
+  const def=rt();
+  $("#rt-help").textContent=def.help||"";
+  const wrap=$("#recwrap");wrap.innerHTML="";
+  recsOf(def.id).forEach(rec=>wrap.appendChild(renderRecord(rec,def)));
+  if(def.cardinality==="multi"){
+    const bar=document.createElement("div");bar.className="addbar";
+    const b=document.createElement("button");b.className="primary";b.textContent="＋ New record: "+def.label;
+    b.onclick=async()=>{
+      const extra={};(def.extras||[]).forEach(e=>{if(e.default)extra[e.id]=e.default});
+      const res=await api("/api/record",{method:"POST",headers:{"Content-Type":"application/json"},
+        body:JSON.stringify({annotator:S.annotator,paper:S.paper,action:"create",rtype:def.id,extra})});
+      S.records.push({uid:res.uid,rtype:def.id,extra});
+      renderTabs();renderRight();
+    };
+    bar.appendChild(b);wrap.appendChild(bar);
+  }
+}
+
+function renderRecord(rec,def){
+  const card=document.createElement("div");card.className="record";
+  /* head */
+  const head=document.createElement("div");head.className="rec-head";
+  head.innerHTML=`<span class="rlabel">${esc(recLabel(rec,def))}</span><span class="uid">#${rec.uid}</span>`;
+  const ex=document.createElement("span");ex.className="extras";
+  (def.extras||[]).forEach(e=>{
+    const lab=document.createElement("label");lab.textContent=e.label+" ";
+    if(e.type==="flag"){
+      const c=document.createElement("input");c.type="checkbox";c.checked=!!rec.extra[e.id];
+      c.onchange=()=>{rec.extra[e.id]=c.checked;saveExtra(rec);renderRight()};
+      lab.prepend(c);
+    }else{
+      const s=document.createElement("select");
+      s.innerHTML="<option value=''>—</option>"+e.options.map(o=>`<option ${rec.extra[e.id]===o?"selected":""}>${o}</option>`).join("");
+      s.onchange=()=>{rec.extra[e.id]=s.value;saveExtra(rec);renderTabs();renderRight()};
+      lab.appendChild(s);
+    }
+    if(e.hint)lab.title=e.hint;
+    ex.appendChild(lab);
+  });
+  (def.extras||[]).filter(e=>e.type==="fk").forEach(()=>{});
+  head.appendChild(ex);
+  if(def.cardinality==="multi"){
+    const del=document.createElement("button");del.textContent="Delete";del.style.marginLeft="auto";
+    del.onclick=async()=>{
+      if(!confirm("Delete this record and all its field annotations?"))return;
+      await api("/api/record",{method:"POST",headers:{"Content-Type":"application/json"},
+        body:JSON.stringify({annotator:S.annotator,paper:S.paper,action:"delete",uid:rec.uid})});
+      S.records=S.records.filter(r=>r.uid!==rec.uid);renderTabs();renderRight();
+    };
+    head.appendChild(del);
+  }
+  card.appendChild(head);
+  /* fk-type extras (model_fk) rendered as a field-like row */
+  (def.extras||[]).filter(e=>e.type==="fk").forEach(e=>{
+    const g=document.createElement("div");g.className="field";
+    g.innerHTML=`<div class="f-head"><span class="f-id">${e.id}</span><span class="f-label">${esc(e.label)}</span></div>`;
+    g.appendChild(fkBox(e.fk_target,rec.extra[e.id]||[],ids=>{rec.extra[e.id]=ids;saveExtra(rec)}));
+    if(e.hint){const h=document.createElement("div");h.className="f-hint";h.textContent=e.hint;g.appendChild(h)}
+    card.appendChild(g);
+  });
+  /* groups */
+  const na=naSet();
+  const groups=def.groups||[{title:null,fields:def.fields}];
+  const simple=rec.extra.role&&rec.extra.role!=="proposed";
+  groups.forEach(gr=>{
+    if(gr.trigger&&!rec.extra[gr.trigger])return;
+    const g=document.createElement("div");g.className="group";
+    if(gr.title){
+      const t=document.createElement("div");t.className="group-title";
+      t.innerHTML=`<span class="tri">▾</span> ${esc(gr.title)}`;
+      t.onclick=()=>g.classList.toggle("closed");
+      g.appendChild(t);
+      if(simple&&!/M1–M4|framework/i.test(gr.title))g.classList.add("closed");
+    }
+    gr.fields.forEach(f=>g.appendChild(renderField(rec,f,na)));
+    card.appendChild(g);
+  });
+  if(simple){
+    const n=document.createElement("div");n.className="f-hint";n.style.padding="6px 12px";
+    n.textContent="role ≠ proposed: abbreviated record suffices; other groups collapsed, expand as needed.";
+    card.appendChild(n);
+  }
+  return card;
+}
+
+function fkBox(target,selected,onchange){
+  const targets=Array.isArray(target)?target:[target];
+  const box=document.createElement("div");box.className="fk-box";
+  let any=false;
+  targets.forEach(tg=>{
+    const tdef=S.schema.record_types.find(r=>r.id===tg);
+    recsOf(tg).forEach(r=>{
+      any=true;
+      const lab=document.createElement("label");
+      const c=document.createElement("input");c.type="checkbox";
+      c.checked=selected.includes(r.uid);
+      c.onchange=()=>{
+        const s=new Set(selected);c.checked?s.add(r.uid):s.delete(r.uid);
+        selected=[...s];onchange(selected);
+      };
+      lab.appendChild(c);
+      lab.append(`[${tdef.label.split("·").pop().trim()}] ${recLabel(r,tdef)} #${r.uid}`);
+      box.appendChild(lab);
+    });
+  });
+  if(!any){box.innerHTML=`<span class="muted" style="font-size:12px">No target records yet — create a ${targets.join("/")} record first</span>`}
+  return box;
+}
+
+function renderField(rec,f,na){
+  const uid=rec.uid;
+  const pl=getPayload(uid,f.id);
+  const el=document.createElement("div");
+  el.className="field";el.dataset.uid=uid;el.dataset.fid=f.id;
+  const isNA=na.has(f.id.toUpperCase());
+  if(isNA)el.classList.add("na");
+  if(S.active&&S.active.uid===uid&&S.active.fid===f.id)el.classList.add("active");
+
+  const badges=[
+    f.novel?'<span class="badge b-novel">novel</span>':"",
+    f.operational?'<span class="badge b-op">operational</span>':"",
+    f.gold?'<span class="badge b-gold">gold priority</span>':"",
+    f.verbatim?'<span class="badge b-verb">verbatim</span>':"",
+    isNA?'<span class="badge b-na">L1 N/A</span>':""
+  ].join("");
+  const done=pl.status?`<span class="f-done">● ${pl.status}</span>`:"";
+  el.innerHTML=`<div class="f-head"><span class="f-id">${f.id}</span><span class="f-label">${esc(f.label)}</span>${badges}${done}</div>`;
+  el.querySelector(".f-head").onclick=()=>activate(uid,f.id);
+
+  const body=document.createElement("div");body.className="f-body";
+  /* status */
+  const st=document.createElement("select");
+  st.innerHTML="<option value=''>status…</option>"+S.schema.attributes.status.map(s=>`<option value="${s.v}" ${pl.status===s.v?"selected":""}>${s.label}</option>`).join("");
+  st.onchange=()=>{pl.status=st.value;saveField(uid,f.id,pl,true)};
+  body.appendChild(st);
+  /* granularity */
+  const gr=document.createElement("select");
+  gr.innerHTML="<option value=''>granularity…</option>"+S.schema.attributes.granularity.map(s=>`<option value="${s.v}" ${pl.granularity===s.v?"selected":""}>${s.label}</option>`).join("");
+  gr.onchange=()=>{pl.granularity=gr.value;saveField(uid,f.id,pl)};
+  body.appendChild(gr);
+  /* value */
+  body.appendChild(valueEditor(f,pl,uid));
+  /* defer_target */
+  if(pl.status==="absent_deferred"){
+    const d=document.createElement("input");d.type="text";d.className="full";
+    d.placeholder="defer_target: where it points (e.g. Appendix B.1). First confirm it is truly absent from the documents at hand.";
+    d.value=pl.defer_target||"";
+    d.oninput=()=>{pl.defer_target=d.value;saveField(uid,f.id,pl)};
+    body.appendChild(d);
+  }
+  /* hint */
+  if(f.hint){const h=document.createElement("div");h.className="f-hint";h.textContent=f.hint;body.appendChild(h)}
+  /* evidence */
+  body.appendChild(evidenceList(uid,f.id,pl));
+  /* note */
+  const note=document.createElement("input");note.type="text";note.className="full";
+  note.placeholder="Note: reason for uncertain, internal contradictions, ...";note.value=pl.note||"";
+  note.style.fontSize="12px";
+  note.oninput=()=>{pl.note=note.value;saveField(uid,f.id,pl)};
+  body.appendChild(note);
+
+  el.appendChild(body);
+  el.addEventListener("mousedown",()=>activate(uid,f.id,el),true);
+  return el;
+}
+
+function valueEditor(f,pl,uid){
+  if(f.type==="enum_field"){
+    const s=document.createElement("select");s.className="full";
+    s.innerHTML="<option value=''>value…</option>"+f.options.map(o=>`<option ${pl.value===o?"selected":""}>${o}</option>`).join("");
+    s.onchange=()=>{pl.value=s.value;saveField(uid,f.id,pl)};
+    return s;
+  }
+  if(f.type==="axes"){
+    const box=document.createElement("div");box.className="full";
+    pl.axes=pl.axes||[];
+    const draw=()=>{
+      box.innerHTML="";
+      pl.axes.forEach((ax,i)=>{
+        const row=document.createElement("div");row.className="axes-row";
+        const a=document.createElement("input");a.type="text";a.placeholder="axis (patient/video/image…)";a.value=ax.axis||"";
+        a.oninput=()=>{ax.axis=a.value;saveField(uid,f.id,pl)};
+        const s=document.createElement("select");
+        s.innerHTML=["disjoint","overlap","unknown"].map(o=>`<option ${ax.status===o?"selected":""}>${o}</option>`).join("");
+        s.onchange=()=>{ax.status=s.value;saveField(uid,f.id,pl)};
+        const d=document.createElement("button");d.textContent="×";
+        d.onclick=()=>{pl.axes.splice(i,1);saveField(uid,f.id,pl);draw()};
+        row.append(a,s,d);box.appendChild(row);
+      });
+      const add=document.createElement("button");add.textContent="＋ Add axis";
+      add.onclick=()=>{pl.axes.push({axis:"",status:"unknown"});draw()};
+      box.appendChild(add);
+    };
+    draw();return box;
+  }
+  if(f.type==="fk"||f.type==="fk2"){
+    const box=document.createElement("div");box.className="full";
+    pl.fk=pl.fk||[];
+    box.appendChild(fkBox(f.type==="fk2"?f.fk_targets:f.fk_target,pl.fk,ids=>{pl.fk=ids;saveField(uid,f.id,pl)}));
+    if(f.allow_no_anchor){
+      const lab=document.createElement("label");lab.style.cssText="font-size:12px;display:flex;gap:4px;margin-top:4px";
+      const c=document.createElement("input");c.type="checkbox";c.checked=!!pl.no_anchor;
+      c.onchange=()=>{pl.no_anchor=c.checked;saveField(uid,f.id,pl)};
+      lab.append(c,"no_anchor (explicit: anchors to no reported result)");
+      box.appendChild(lab);
+    }
+    const v=document.createElement("textarea");v.placeholder="Supplementary note, e.g. M7 selection action";v.value=pl.value||"";
+    v.style.marginTop="4px";
+    v.oninput=()=>{pl.value=v.value;saveField(uid,f.id,pl)};
+    box.appendChild(v);
+    return box;
+  }
+  /* text (default) */
+  const t=document.createElement("textarea");t.className="full";t.value=pl.value||"";
+  t.placeholder=f.suggest?("e.g. "+f.suggest.join(" / ")):"Value, verbatim from paper; judgments go downstream";
+  t.oninput=()=>{pl.value=t.value;saveField(uid,f.id,pl)};
+  return t;
+}
+
+function evidenceList(uid,fid,pl){
+  const box=document.createElement("div");box.className="ev-list";
+  (pl.evidence||[]).forEach((ev,i)=>{
+    const row=document.createElement("div");row.className="ev";
+    const hasBox=!!(ev.pdf_anchor&&ev.pdf_anchor.boxes&&ev.pdf_anchor.boxes.length);
+    const g=ev.grounded===true?'<span class="g-ok">✓</span>'
+      :ev.grounded===false&&ev.origin==="pdf"&&hasBox?'<span class="g-pdf" title="Selected on the PDF but not found in the converted text (likely conversion damage). The PDF location is kept; consider ticking dmg.">◐</span>'
+      :ev.grounded===false?'<span class="g-bad" title="Grounding mismatch: quote is not an exact substring of the fulltext; verify and fix">✗</span>':"…";
+    row.innerHTML=`${g}`;
+    const q=document.createElement("span");q.className="q";q.textContent=ev.quote;q.title="Click to locate in the left pane";
+    q.onclick=()=>locateQuote(ev);
+    row.appendChild(q);
+    if(hasBox&&PV.doc){const t=document.createElement("span");t.className="pdf-tag";t.textContent="PDF p."+ev.pdf_anchor.boxes[0].page;
+      t.title="Show on the PDF";t.onclick=()=>{if(S.view==="text")setView("split");setHl(ev.pdf_anchor.boxes,"ev")};row.appendChild(t)}
+    const sec=document.createElement("select");
+    sec.innerHTML=S.schema.attributes.evidence_sections.map(s=>`<option ${ev.section===s?"selected":""}>${s}</option>`).join("");
+    sec.onchange=()=>{ev.section=sec.value;saveField(uid,fid,pl)};
+    row.appendChild(sec);
+    S.schema.attributes.evidence_flags.forEach(fl=>{
+      const lab=document.createElement("label");lab.title=fl.label;
+      const c=document.createElement("input");c.type="checkbox";c.checked=!!(ev.flags&&ev.flags[fl.v]);
+      c.onchange=()=>{ev.flags=ev.flags||{};ev.flags[fl.v]=c.checked;saveField(uid,fid,pl)};
+      lab.append(c,fl.v.replace("pipeline_damage","dmg").replace("figure_only","fig"));
+      row.appendChild(lab);
+    });
+    const d=document.createElement("button");d.textContent="×";
+    d.onclick=()=>{pl.evidence.splice(i,1);saveField(uid,fid,pl,true)};
+    row.appendChild(d);
+    box.appendChild(row);
+  });
+  const add=document.createElement("button");
+  add.textContent="＋ Figure/table evidence (no selection)";
+  add.style.cssText="font-size:11px;align-self:flex-start";
+  add.title="Use when the value only exists in a figure or damaged table: paste the caption verbatim (grounds if it matches) or a locator like Figure 3 left panel";
+  add.onclick=()=>{
+    const q=prompt("Figure/table evidence: paste the caption/table title verbatim if possible (it can then be grounded), otherwise a locator description, e.g. Figure 3 left panel");
+    if(!q)return;
+    pl.evidence=pl.evidence||[];
+    pl.evidence.push({quote:q.replace(/\s+/g," ").trim(),section:"figure",flags:{figure_only:true},grounded:null,char_span:null});
+    if(!pl.status)pl.status="stated";
+    saveField(uid,fid,pl,true);
+  };
+  box.appendChild(add);
+  return box;
+}
+
+const normQ=t=>t.replace(/\s+/g," ").trim().toLowerCase();
+function locateQuote(ev){
+  if(S.layout){
+    const boxes=ev.pdf_anchor&&ev.pdf_anchor.boxes,ids=ev.pdf_anchor&&ev.pdf_anchor.blocks;
+    if(S.view==="pdf"&&boxes&&boxes.length){setHl(boxes,"ev");return}
+    if(S.view==="pdf"||S.view==="raw")setView("split");
+    const fq=normQ(ev.quote);
+    let el=ids&&ids.length?$(`#textpane .tb[data-b="${ids[0]}"]`):null;
+    if(!el)el=$$("#textpane .tb").find(b=>normQ(b.textContent).includes(fq))||null;
+    if(el){
+      $$("#textpane .tb.cur").forEach(x=>x.classList.remove("cur"));el.classList.add("cur");
+      el.scrollIntoView({block:"center",behavior:"smooth"});el.classList.add("flash");setTimeout(()=>el.classList.remove("flash"),2500);
+    }
+    const bx=boxes&&boxes.length?boxes:el?S.layout.blocks[+el.dataset.b].boxes:null;
+    if(bx)setHl(bx,"ev");
+    if(!el&&!bx)alert("Not found in the text or on the PDF. char_span (folded coords) = "+JSON.stringify(ev.char_span));
+    return;
+  }
+  if(S.view==="pdf")setView("text");
+  if(S.isMd){
+    const fq=ev.quote.replace(/\s+/g," ").trim().toLowerCase();
+    for(const b of $("#textpane").querySelectorAll("p,h2,h3,h4,h5,h6,tr")){
+      if(b.textContent.replace(/\s+/g," ").toLowerCase().includes(fq)){
+        b.scrollIntoView({block:"center",behavior:"smooth"});
+        b.classList.add("flash");setTimeout(()=>b.classList.remove("flash"),2500);
+        return;
+      }
+    }
+    setView("raw");   // 渲染视图找不到, 退到源文件视图按原逻辑高亮
+  }
+  const raw=S.rawText, q=ev.quote;
+  let i=raw.indexOf(q);
+  if(i<0){ /* whitespace-insensitive fallback */
+    const pat=q.trim().split(/\s+/).map(w=>w.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")).join("\\s+");
+    const m=raw.match(new RegExp(pat));
+    if(m){renderText(m.index,m.index+m[0].length);return}
+    alert("Not found in the displayed text. char_span (folded coords) = "+JSON.stringify(ev.char_span));return;
+  }
+  renderText(i,i+q.length);
+}
+
+/* ---------------- save ---------------- */
+function activate(uid,fid,el){
+  const prev=S.active;
+  S.active={uid,fid};
+  if(!prev||prev.uid!==uid||prev.fid!==fid){
+    $$(".field.active").forEach(x=>x.classList.remove("active"));
+    (el||document.querySelector(`.field[data-uid="${uid}"][data-fid="${fid}"]`))?.classList.add("active");
+  }
+}
+function saveExtra(rec){
+  api("/api/record",{method:"POST",headers:{"Content-Type":"application/json"},
+    body:JSON.stringify({annotator:S.annotator,paper:S.paper,action:"extra",uid:rec.uid,extra:rec.extra})});
+}
+function saveField(uid,fid,pl,rerender){
+  const key=uid+"."+fid;
+  clearTimeout(S.saveTimers[key]);
+  S.pendingSaves=S.pendingSaves||{};
+  const run=S.pendingSaves[key]=async()=>{
+    delete S.saveTimers[key];delete S.pendingSaves[key];
+    const res=await api("/api/field",{method:"POST",headers:{"Content-Type":"application/json"},
+      body:JSON.stringify({paper:S.paper,record_uid:uid,field_id:fid,payload:pl})});
+    S.fields[uid][fid]=res.payload;
+    updateProgress();
+    if(rerender)renderRight();
+    pollSync();
+  };
+  S.saveTimers[key]=setTimeout(run,rerender?0:600);
+  const chip=$("#h-sync");chip.classList.remove("ok","err");chip.classList.add("pending");chip.textContent="Saving…";
+}
+function updateProgress(){
+  let n=0;
+  Object.values(S.fields).forEach(m=>Object.values(m).forEach(p=>{
+    if(isFilled(p))n++;
+  }));
+  $("#h-progress").textContent=n+" fields annotated";
+}
+</script>
+</body>
+</html>

app/store.py

@@ -0,0 +1,397 @@
+"""存储层: 标注数据 + 论文语料, 两种后端同一接口。
+
+- local: 标注存 03_annotation/data/store/<annotator>/annotations/<paper>.json, 论文按 manifest 读本地语料树(开发 / 离线用)
+- github: 默认一个私有仓库管所有(0925 定): papers/ 放论文, annotations/<annotator>/ 放各人标注。
+  服务器用一个 token(Rong 的 fine-grained PAT)读写, 标注人不需要 GitHub 账号, 只能经服务器读写自己那份。
+  (也支持每人一个仓库: ANNOTATORS_JSON 里给某人配 "repo", 其标注写进那个仓库的 annotations/。)
+
+标注文件 = 一篇论文 × 一个标注人一份 JSON(records + fields + events), 每次同步一个 commit,
+git 历史本身就是第二层审计痕迹。
+"""
+import base64
+import hashlib
+import json
+import os
+import threading
+import time
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+import httpx
+
+GITHUB_API = os.environ.get("GITHUB_API_URL", "https://api.github.com")
+
+
+# ---------- 标注仓库 ----------
+
+class LocalAnnotationStore:
+    def __init__(self, root: Path):
+        self.root = root
+
+    def _path(self, annotator: str, name: str) -> Path:
+        return self.root / annotator / "annotations" / name
+
+    def read(self, annotator: str, name: str) -> Tuple[Optional[bytes], Optional[str]]:
+        p = self._path(annotator, name)
+        if not p.exists():
+            return None, None
+        data = p.read_bytes()
+        return data, str(p.stat().st_mtime_ns)
+
+    def write(self, annotator: str, name: str, data: bytes, sha: Optional[str], message: str) -> str:
+        p = self._path(annotator, name)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        tmp = p.with_suffix(p.suffix + ".tmp")
+        tmp.write_bytes(data)
+        tmp.replace(p)
+        return str(p.stat().st_mtime_ns)
+
+    def list(self, annotator: str) -> List[str]:
+        d = self.root / annotator / "annotations"
+        if not d.is_dir():
+            return []
+        return sorted(f.name for f in d.iterdir() if f.suffix == ".json")
+
+
+class GitHubAnnotationStore:
+    """annotator → (仓库, 目录)。通过 Contents API 读写, 每次写一个 commit。"""
+
+    def __init__(self, token: str, locations: Dict[str, Tuple[str, str]], branch: Optional[str] = None,
+                 client: Optional[httpx.Client] = None):
+        self.locations = locations
+        self.branch = branch
+        self.client = client or httpx.Client(base_url=GITHUB_API, timeout=30)
+        self.headers = {"Authorization": f"Bearer {token}",
+                        "Accept": "application/vnd.github+json",
+                        "X-GitHub-Api-Version": "2022-11-28"}
+
+    def _loc(self, annotator: str) -> Tuple[str, str]:
+        if annotator not in self.locations:
+            raise KeyError(f"no storage location for annotator {annotator}")
+        return self.locations[annotator]
+
+    def _url(self, annotator: str, name: str = "") -> str:
+        repo, directory = self._loc(annotator)
+        return f"/repos/{repo}/contents/{directory}" + (f"/{name}" if name else "")
+
+    def read(self, annotator: str, name: str) -> Tuple[Optional[bytes], Optional[str]]:
+        params = {"ref": self.branch} if self.branch else None
+        r = self.client.get(self._url(annotator, name),
+                            headers=self.headers, params=params)
+        if r.status_code == 404:
+            return None, None
+        r.raise_for_status()
+        meta = r.json()
+        if meta.get("encoding") == "base64" and meta.get("content"):
+            return base64.b64decode(meta["content"]), meta["sha"]
+        # >1MB 的文件 content 为空, 走 raw
+        raw = self.client.get(self._url(annotator, name),
+                              headers={**self.headers, "Accept": "application/vnd.github.raw+json"},
+                              params=params)
+        raw.raise_for_status()
+        return raw.content, meta["sha"]
+
+    def write(self, annotator: str, name: str, data: bytes, sha: Optional[str], message: str) -> str:
+        body = {"message": message, "content": base64.b64encode(data).decode()}
+        if sha:
+            body["sha"] = sha
+        if self.branch:
+            body["branch"] = self.branch
+        url = self._url(annotator, name)
+        r = self.client.put(url, headers=self.headers, json=body)
+        if r.status_code in (409, 422):
+            # sha 过期(别处改过文件): 取最新 sha 重试一次; 服务器是唯一写入方, 以内存版本为准
+            _, cur = self.read(annotator, name)
+            if cur:
+                body["sha"] = cur
+            else:
+                body.pop("sha", None)
+            r = self.client.put(url, headers=self.headers, json=body)
+        r.raise_for_status()
+        return r.json()["content"]["sha"]
+
+    def list(self, annotator: str) -> List[str]:
+        params = {"ref": self.branch} if self.branch else None
+        r = self.client.get(self._url(annotator), headers=self.headers, params=params)
+        if r.status_code == 404:
+            return []
+        r.raise_for_status()
+        return sorted(e["name"] for e in r.json() if e["type"] == "file" and e["name"].endswith(".json"))
+
+
+# ---------- 论文语料 ----------
+
+class LocalPapers:
+    """manifest 里的路径相对 root。默认 root = 1.Reproducibility/, manifest = 03_annotation/papers/manifest.json。"""
+
+    def __init__(self, root: Path, manifest_path: Path):
+        self.root = root
+        self.manifest_path = manifest_path
+
+    @property
+    def ref(self) -> str:
+        return "local"
+
+    def manifest(self) -> dict:
+        return json.loads(self.manifest_path.read_text(encoding="utf-8"))
+
+    def text(self, relpath: str) -> str:
+        return (self.root / relpath).read_text(encoding="utf-8", errors="ignore")
+
+    def pdf_path(self, relpath: str) -> Path:
+        return self.root / relpath
+
+    # ---- 1003: 上传论文 / 论文池(本地: 写在 manifest 旁的 uploads/ 与 pool.json)
+
+    def pool(self) -> Optional[List[str]]:
+        p = self.manifest_path.parent / "pool.json"
+        return json.loads(p.read_text(encoding="utf-8"))["papers"] if p.exists() else None
+
+    def set_pool(self, papers: List[str], message: str = ""):
+        (self.manifest_path.parent / "pool.json").write_text(
+            json.dumps({"papers": papers}, ensure_ascii=False, indent=1), encoding="utf-8")
+
+    def add_paper(self, pid: str, files: Dict[str, bytes], entry: dict, message: str = ""):
+        """只增不改: pid 已存在就报错(全文是 char_span 坐标系, 冻结)。entry 里的文件字段用 files 的键名。"""
+        m = self.manifest()
+        if pid in m["papers"]:
+            raise FileExistsError(pid)
+        d = self.manifest_path.parent / "uploads" / pid
+        d.mkdir(parents=True, exist_ok=True)
+        for name, data in files.items():
+            (d / name).write_bytes(data)
+        rel = lambda n: os.path.relpath(d / n, self.root) if n else None  # noqa: E731
+        m["papers"][pid] = {**entry, "fulltext": rel(entry["fulltext"]), "pdf": rel(entry.get("pdf")),
+                            "layout": rel(entry.get("layout"))}
+        self.manifest_path.write_text(json.dumps(m, ensure_ascii=False, indent=2), encoding="utf-8")
+
+
+class GitHubPapers:
+    """仓库里 subdir/(默认 papers/)放 manifest.json, manifest 里的路径相对 subdir。
+    启动时把 ref 钉成「最后一次改动 subdir 的 commit」: 本进程内所有读取都来自同一个快照, sha 写进每份标注,
+    保证 char_span 坐标系可追溯(md/txt 冻结纪律)。用最后改动 subdir 的 commit 而不是分支头,
+    是因为标注和论文同仓库时每次保存都会产生新 commit, 按分支头记会把"论文没变"误报成快照变了。"""
+
+    def __init__(self, token: str, repo: str, ref: str, cache_dir: Path, subdir: str = "papers",
+                 client: Optional[httpx.Client] = None):
+        self.repo = repo
+        self.branch = ref
+        self.subdir = subdir.strip("/")
+        self.client = client or httpx.Client(base_url=GITHUB_API, timeout=120)
+        self.headers = {"Authorization": f"Bearer {token}",
+                        "X-GitHub-Api-Version": "2022-11-28"}
+        params = {"sha": ref, "per_page": 1}
+        if self.subdir:
+            params["path"] = self.subdir
+        r = self.client.get(f"/repos/{repo}/commits", params=params,
+                            headers={**self.headers, "Accept": "application/vnd.github+json"})
+        r.raise_for_status()
+        commits = r.json()
+        if not commits:
+            raise RuntimeError(f"no commits touching {self.subdir or '/'} on {repo}@{ref}")
+        self._sha = commits[0]["sha"]
+        self.cache_dir = cache_dir / self._sha[:12]
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        self._manifest = None
+        self._pool = False                       # False = 还没读; None = 仓库里没有 pool.json
+        self._text_cache: Dict[str, str] = {}
+        self._lock = threading.Lock()
+
+    @property
+    def ref(self) -> str:
+        return self._sha
+
+    def _raw(self, relpath: str) -> bytes:
+        full = f"{self.subdir}/{relpath}" if self.subdir else relpath
+        r = self.client.get(f"/repos/{self.repo}/contents/{full}",
+                            headers={**self.headers, "Accept": "application/vnd.github.raw+json"},
+                            params={"ref": self._sha})
+        r.raise_for_status()
+        return r.content
+
+    def manifest(self) -> dict:
+        if self._manifest is None:
+            self._manifest = json.loads(self._raw("manifest.json"))
+        return self._manifest
+
+    def text(self, relpath: str) -> str:
+        with self._lock:
+            if relpath not in self._text_cache:
+                self._text_cache[relpath] = self._raw(relpath).decode("utf-8", errors="ignore")
+            return self._text_cache[relpath]
+
+    def pdf_path(self, relpath: str) -> Path:
+        local = self.cache_dir / relpath
+        if not local.exists():
+            local.parent.mkdir(parents=True, exist_ok=True)
+            tmp = local.with_suffix(".part")
+            tmp.write_bytes(self._raw(relpath))
+            tmp.replace(local)
+        return local
+
+    # ---- 1003: 上传论文 / 论文池。一次上传 = 一个 commit(Git Data API), 之后快照 ref 前移到这个 commit:
+    # 已有论文的文件不变(只增不改), 所以旧标注的 char_span 仍有效; 各文档的 papers_refs_seen 会记下这次前移。
+
+    def _api(self, method: str, url: str, **kw):
+        r = self.client.request(method, f"/repos/{self.repo}{url}",
+                                headers={**self.headers, "Accept": "application/vnd.github+json"}, **kw)
+        r.raise_for_status()
+        return r.json() if r.content else None
+
+    def _head_json(self, relpath: str):
+        """分支最新版的某个 papers/ 文件(不是钉住的快照), 改 manifest / pool 时以它为底, 防丢更新。"""
+        full = f"{self.subdir}/{relpath}" if self.subdir else relpath
+        r = self.client.get(f"/repos/{self.repo}/contents/{full}", params={"ref": self.branch},
+                            headers={**self.headers, "Accept": "application/vnd.github.raw+json"})
+        if r.status_code == 404:
+            return None
+        r.raise_for_status()
+        return json.loads(r.content)
+
+    def _commit(self, files: Dict[str, bytes], message: str):
+        with self._lock:
+            blobs = {p: self._api("POST", "/git/blobs", json={"content": base64.b64encode(b).decode(),
+                                                               "encoding": "base64"})["sha"]
+                     for p, b in files.items()}
+            for _ in range(5):                       # 标注同步也在往同一分支提交: 非快进就重来
+                head = self._api("GET", f"/git/ref/heads/{self.branch}")["object"]["sha"]
+                base_tree = self._api("GET", f"/git/commits/{head}")["tree"]["sha"]
+                tree = self._api("POST", "/git/trees", json={"base_tree": base_tree, "tree": [
+                    {"path": (f"{self.subdir}/{p}" if self.subdir else p), "mode": "100644", "type": "blob",
+                     "sha": s} for p, s in blobs.items()]})["sha"]
+                commit = self._api("POST", "/git/commits",
+                                   json={"message": message, "tree": tree, "parents": [head]})["sha"]
+                r = self.client.patch(f"/repos/{self.repo}/git/refs/heads/{self.branch}", json={"sha": commit},
+                                      headers={**self.headers, "Accept": "application/vnd.github+json"})
+                if r.status_code == 422:
+                    continue
+                r.raise_for_status()
+                self._sha = commit
+                self.cache_dir = self.cache_dir.parent / commit[:12]
+                self.cache_dir.mkdir(parents=True, exist_ok=True)
+                self._manifest = None
+                self._pool = False
+                return commit
+            raise RuntimeError("could not commit to GitHub (branch kept moving)")
+
+    def pool(self) -> Optional[List[str]]:
+        if self._pool is False:
+            r = self.client.get(f"/repos/{self.repo}/contents/{self.subdir}/pool.json", params={"ref": self._sha},
+                                headers={**self.headers, "Accept": "application/vnd.github.raw+json"})
+            self._pool = json.loads(r.content)["papers"] if r.status_code == 200 else None
+        return self._pool
+
+    def set_pool(self, papers: List[str], message: str = "papers: update annotator pool"):
+        self._commit({"pool.json": json.dumps({"papers": papers}, ensure_ascii=False, indent=1).encode()}, message)
+
+    def add_paper(self, pid: str, files: Dict[str, bytes], entry: dict, message: str = ""):
+        m = self._head_json("manifest.json") or {"papers": {}}
+        if pid in m["papers"]:
+            raise FileExistsError(pid)
+        hashes = {n: hashlib.sha256(b).hexdigest() for n, b in files.items()}
+        rel = lambda n: f"{pid}/{n}" if n else None  # noqa: E731
+        m["papers"][pid] = {**entry, "fulltext": rel(entry["fulltext"]), "pdf": rel(entry.get("pdf")),
+                            "layout": rel(entry.get("layout")), "fulltext_sha256": hashes[entry["fulltext"]]}
+        out = {f"{pid}/{n}": b for n, b in files.items()}
+        out["manifest.json"] = json.dumps(m, ensure_ascii=False, indent=2).encode()
+        return self._commit(out, message or f"papers: add {pid}")
+
+
+# ---------- 写回缓存 ----------
+
+class DocCache:
+    """(annotator, paper) → 标注文档, 内存里改, 后台线程每 flush_seconds 秒把脏文档写回存储。
+    每次改动都立即在内存生效(界面零延迟); 同步状态通过 status() 暴露给前端的同步指示。"""
+
+    def __init__(self, store, flush_seconds: float = 15.0):
+        self.store = store
+        self.flush_seconds = flush_seconds
+        self.docs: Dict[Tuple[str, str], dict] = {}
+        self.shas: Dict[Tuple[str, str], Optional[str]] = {}
+        self.dirty: Dict[Tuple[str, str], int] = {}      # key → 脏版本号
+        self.pending_msgs: Dict[Tuple[str, str], List[str]] = {}
+        self.lock = threading.RLock()
+        self.flush_lock = threading.Lock()
+        self.last_ok: Dict[str, float] = {}
+        self.last_error: Dict[str, Optional[str]] = {}
+        self._stop = threading.Event()
+        self._thread: Optional[threading.Thread] = None
+
+    @staticmethod
+    def path_for(paper: str) -> str:
+        return f"{paper}.json"
+
+    def get(self, annotator: str, paper: str, papers_ref: str) -> dict:
+        key = (annotator, paper)
+        with self.lock:
+            if key in self.docs:
+                return self.docs[key]
+        data, sha = self.store.read(annotator, self.path_for(paper))
+        with self.lock:
+            if key in self.docs:           # 并发加载, 以先到的为准
+                return self.docs[key]
+            if data:
+                doc = json.loads(data)
+            else:
+                doc = {"paper": paper, "annotator": annotator, "papers_ref": papers_ref,
+                       "created_ts": time.time(), "records": {}, "fields": {}, "events": []}
+            self.docs[key] = doc
+            self.shas[key] = sha
+            return doc
+
+    def mark_dirty(self, annotator: str, paper: str, msg: str):
+        key = (annotator, paper)
+        with self.lock:
+            self.dirty[key] = self.dirty.get(key, 0) + 1
+            self.pending_msgs.setdefault(key, []).append(msg)
+
+    def flush(self) -> None:
+        with self.flush_lock:
+            with self.lock:
+                work = [(k, v, json.dumps(self.docs[k], ensure_ascii=False, indent=1).encode("utf-8"),
+                         self.pending_msgs.get(k, []))
+                        for k, v in self.dirty.items()]
+            for key, version, data, msgs in work:
+                annotator, paper = key
+                n = len(msgs)
+                message = f"{annotator} · {paper} · {n} change{'s' if n != 1 else ''}\n\n" + "\n".join(msgs[:50])
+                try:
+                    sha = self.store.write(annotator, self.path_for(paper), data, self.shas.get(key), message)
+                except Exception as e:                       # 保持脏, 下一轮重试
+                    self.last_error[annotator] = f"{type(e).__name__}: {e}"[:300]
+                    continue
+                with self.lock:
+                    self.shas[key] = sha
+                    if self.dirty.get(key) == version:       # 期间没有新改动才清脏
+                        self.dirty.pop(key, None)
+                        self.pending_msgs.pop(key, None)
+                    else:
+                        self.pending_msgs[key] = self.pending_msgs.get(key, [])[n:]
+                    self.last_ok[annotator] = time.time()
+                    self.last_error[annotator] = None
+
+    def status(self, annotator: str) -> dict:
+        with self.lock:
+            pending = sum(1 for (a, _p) in self.dirty if a == annotator)
+        return {"pending": pending, "last_ok": self.last_ok.get(annotator),
+                "error": self.last_error.get(annotator), "flush_seconds": self.flush_seconds}
+
+    def _loop(self):
+        while not self._stop.wait(self.flush_seconds):
+            self.flush()
+
+    def start(self):
+        if self._thread is None:
+            self._thread = threading.Thread(target=self._loop, name="doc-flusher", daemon=True)
+            self._thread.start()
+
+    def stop(self):
+        self._stop.set()
+        self.flush()
+
+
+def env_flag(name: str, default: bool) -> bool:
+    v = os.environ.get(name)
+    if v is None:
+        return default
+    return v.strip().lower() in ("1", "true", "yes", "on")

app/textconv.py

@@ -0,0 +1,529 @@
+"""PDF / PMC XML → 标注系统用的「人读 md + layout.json」(1003)。
+
+被两处使用(同一份代码):
+  - 01_collection/scripts/make_annotation_text.py   批量转语料
+  - 标注服务器的「上传论文」(main.py 以子进程调用本文件的 job 子命令, 依赖 docling/pymupdf 可以只装在转换环境里)
+
+来源优先级: PMC 开放获取子集有 JATS XML → 用 XML(官方原文), 块的 PDF 位置在 PDF 文本层里对齐;
+否则 → Docling(版面模型 + TableFormer, 关 OCR), 块位置直接来自 Docling。
+layout.json: 每块 md 的 [start, end) + PDF (page, bbox), bbox 为 PDF point、左上原点, page 从 1 起。
+
+子进程用法:
+    python textconv.py job --out DIR [--pdf X.pdf] [--ident PMCID|DOI|PMID]
+    → DIR/fulltext.md, DIR/layout.json, DIR/paper.pdf, DIR/meta.json(source / pmcid / doi / title / log)
+"""
+import hashlib
+import json
+import re
+import shutil
+import sys
+import unicodedata
+import urllib.parse
+import urllib.request
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+LAYOUT_VERSION = "1003"
+
+
+def sha256(p: Path) -> str:
+    return hashlib.sha256(p.read_bytes()).hexdigest()
+
+
+class Builder:
+    """顺序拼 md, 同时记块坐标。块之间空一行。"""
+
+    def __init__(self):
+        self.parts, self.blocks, self.pos = [], [], 0
+
+    def add(self, md: str, kind: str, boxes=None, **extra):
+        md = md.strip("\n")
+        if not md.strip():
+            return None
+        if self.parts:
+            self.parts.append("\n\n")
+            self.pos += 2
+        start = self.pos
+        self.parts.append(md)
+        self.pos += len(md)
+        b = {"id": len(self.blocks), "kind": kind, "start": start, "end": self.pos,
+             "boxes": boxes or [], **extra}
+        self.blocks.append(b)
+        return b
+
+    @property
+    def md(self) -> str:
+        return "".join(self.parts) + "\n"
+
+
+def one_line(t: str) -> str:
+    return re.sub(r"\s+", " ", t or "").strip()
+
+
+def cell(t: str) -> str:
+    return one_line(t).replace("|", "\\|")
+
+
+def grid_markdown(grid) -> str:
+    """单元格网格 → markdown 表(合并单元格已展开成重复值, 保住列身份)。第一行当表头。"""
+    grid = [[cell(c) for c in r] for r in grid if any((c or "").strip() for c in r)]
+    if not grid:
+        return ""
+    w = max(len(r) for r in grid)
+    grid = [r + [""] * (w - len(r)) for r in grid]
+    lines = ["| " + " | ".join(grid[0]) + " |", "|" + "---|" * w]
+    return "\n".join(lines + ["| " + " | ".join(r) + " |" for r in grid[1:]])
+
+
+# ---------------------------------------------------------------- Docling (PDF only)
+
+def convert_docling(pdf: Path):
+    from docling.datamodel.base_models import InputFormat
+    from docling.datamodel.pipeline_options import PdfPipelineOptions
+    from docling.document_converter import DocumentConverter, PdfFormatOption
+    from docling_core.types.doc import PictureItem, TableItem
+
+    opts = PdfPipelineOptions()
+    opts.do_ocr = False                    # 原生电子版 PDF: 用嵌入文本, 不让 OCR 改字
+    opts.do_table_structure = True
+    conv = DocumentConverter(format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=opts)})
+    doc = conv.convert(str(pdf)).document
+
+    pages = {str(n): [round(p.size.width, 2), round(p.size.height, 2)] for n, p in doc.pages.items()}
+
+    def boxes(item):
+        out = []
+        for pv in getattr(item, "prov", None) or []:
+            h = doc.pages[pv.page_no].size.height
+            bb = pv.bbox.to_top_left_origin(page_height=h)
+            out.append({"page": pv.page_no, "bbox": [round(bb.l, 1), round(bb.t, 1), round(bb.r, 1), round(bb.b, 1)]})
+        return out
+
+    B = Builder()
+    # 归属表/图的 caption 跟着表/图输出; 正文顺序里单独遇到时跳过, 否则会出现两遍
+    owned = {c.cref for it in list(doc.tables) + list(doc.pictures) for c in it.captions}
+    for item, _lvl in doc.iterate_items(traverse_pictures=False):
+        if item.self_ref in owned:
+            continue
+        label = item.label.value
+        if isinstance(item, (TableItem, PictureItem)):
+            for cref in item.captions:
+                cap = cref.resolve(doc)
+                B.add(one_line(cap.text), "caption", boxes(cap))
+            if isinstance(item, TableItem):
+                md = grid_markdown([[c.text for c in row] for row in item.data.grid])
+                B.add(md or "[table — not recovered, see PDF]", "table", boxes(item))
+            else:
+                B.add("[figure — see PDF]", "figure", boxes(item))
+            continue
+        text = one_line(getattr(item, "text", ""))
+        if label == "text" and re.fullmatch(r"\d{1,4}", text):
+            continue                       # 投稿版页边行号(000 001 …), 每个都会被识别成一块
+        link = getattr(item, "hyperlink", None)
+        if link and not str(link).startswith("mailto:") and str(link) not in text:
+            text = f"{text} <{link}>"      # PyMuPDF 版只剩锚词的超链接, 这里把目标补回来
+        if label == "title":
+            B.add("# " + text, "heading", boxes(item))
+        elif label == "section_header":
+            lv = min(max(getattr(item, "level", 1), 1), 4)
+            B.add("#" * (lv + 1) + " " + text, "heading", boxes(item))
+        elif label == "list_item":
+            mk = (getattr(item, "marker", "") or "").strip()     # 保留原编号 "(2)" / "a." ; 圆点类统一成 "-"
+            B.add(("- " if not mk or mk in "-•·▪◦–*" else mk + " ") + text, "list", boxes(item))
+        elif label == "formula":
+            B.add(text or "[formula — not recovered, see PDF]", "formula", boxes(item))
+        elif label == "code":
+            B.add("```\n" + (getattr(item, "text", "") or "") + "\n```", "code", boxes(item))
+        elif label in ("footnote", "caption", "reference"):
+            B.add(text, label, boxes(item))
+        else:
+            B.add(text, "text", boxes(item))
+    return B, pages, {"source": "docling", "docling_version": _ver("docling")}
+
+
+def _ver(pkg):
+    try:
+        import importlib.metadata as m
+        return m.version(pkg)
+    except Exception:
+        return None
+
+
+# ---------------------------------------------------------------- JATS XML (官方原文)
+
+def tag(el):
+    return el.tag.split("}", 1)[-1]
+
+
+XLINK = "{http://www.w3.org/1999/xlink}href"
+NESTED_BLOCKS = {"table-wrap", "fig", "fig-group", "table-wrap-group", "disp-formula", "list", "boxed-text"}
+
+
+def child(el, name):
+    return el.find("{*}" + name)                  # {*} 同时匹配有 / 无命名空间
+
+
+def inline(el) -> str:
+    """段落内联文本: 保留 ext-link 的 URL、行内公式(tex 或 MathML 文本)、上下标(^ _)。段内嵌的表/图/列表由调用方单独输出。"""
+    out = [el.text or ""]
+    for ch in el:
+        t = tag(ch)
+        if t in NESTED_BLOCKS:
+            pass
+        elif t in ("ext-link", "uri"):
+            txt = one_line("".join(ch.itertext()))
+            href = ch.get(XLINK) or ""
+            out.append(txt + (f" <{href}>" if href and href not in txt else ""))
+        elif t == "inline-formula":
+            tex = ch.find(".//{*}tex-math")
+            out.append(one_line(tex.text if tex is not None and tex.text else "".join(ch.itertext())))
+        elif t == "sup":
+            out.append("^" + "".join(ch.itertext()))
+        elif t == "sub":
+            out.append("_" + "".join(ch.itertext()))
+        else:
+            out.append(inline(ch))
+        out.append(ch.tail or "")
+    return "".join(out)
+
+
+def jats_table(tw) -> str:
+    """table-wrap → markdown 表; 处理 colspan / rowspan(展开成重复单元格, 保住列身份)。"""
+    rows = [tr for tr in tw.iter() if tag(tr) == "tr"]
+    grid, carry = [], {}
+    for tr in rows:
+        row, col = [], 0
+        cells = [c for c in tr if tag(c) in ("td", "th")]
+        ci = 0
+        while ci < len(cells) or col in carry:
+            if col in carry:
+                txt, left = carry[col]
+                row.append(txt)
+                if left <= 1:
+                    del carry[col]
+                else:
+                    carry[col] = (txt, left - 1)
+                col += 1
+                continue
+            c = cells[ci]
+            ci += 1
+            txt = one_line(inline(c))          # grid_markdown 统一转义
+            cs, rs = int(c.get("colspan", 1) or 1), int(c.get("rowspan", 1) or 1)
+            for k in range(cs):
+                row.append(txt)
+                if rs > 1:
+                    carry[col + k] = (txt, rs - 1)
+            col += cs
+        grid.append(row)
+    return grid_markdown(grid)
+
+
+def convert_jats(xml: Path):
+    root = ET.parse(xml).getroot()
+    B = Builder()
+    # 很多 PMC XML 把表/图集中放在 <floats-group>: 插到正文第一次引用它的段落后面, 没被引用的放正文末尾
+    fg = next((x for x in root if tag(x) == "floats-group"), None)
+    floats = {f.get("id"): f for f in (fg if fg is not None else []) if f.get("id")}
+    placed = set()
+
+    def place_floats(p):
+        for x in p.iter():
+            if tag(x) == "xref" and x.get("ref-type") in ("table", "fig"):
+                for rid in (x.get("rid") or "").split():
+                    if rid in floats and rid not in placed:
+                        placed.add(rid)
+                        blocks_of(floats[rid], 1)
+
+    def caption_of(el):
+        lab, cap = child(el, "label"), child(el, "caption")
+        parts = [one_line(inline(lab)) if lab is not None else ""]
+        if cap is not None:
+            parts += [one_line(inline(x)) for x in cap if tag(x) in ("title", "p")]
+        return one_line(" ".join(p for p in parts if p))
+
+    def blocks_of(el, depth):
+        t = tag(el)
+        if t == "sec" or t == "app" or t == "ack":
+            title, label = child(el, "title"), child(el, "label")
+            head = one_line(" ".join(x for x in [inline(label) if label is not None else "",
+                                                  inline(title) if title is not None else ""] if x))
+            if t == "ack" and not head:
+                head = "Acknowledgments"
+            if head:
+                B.add("#" * min(depth + 1, 5) + " " + head, "heading")
+            for ch in el:
+                if tag(ch) not in ("title", "label"):
+                    blocks_of(ch, depth + 1)
+        elif t == "p":
+            B.add(one_line(inline(el)), "text")
+            for ch in el.iter():
+                if ch is not el and tag(ch) in ("table-wrap", "fig", "disp-formula", "list"):
+                    blocks_of(ch, depth)
+            place_floats(el)
+        elif t == "list":
+            for li in el:
+                if tag(li) == "list-item":
+                    B.add("- " + one_line(" ".join(inline(p) for p in li if tag(p) == "p")), "list")
+        elif t == "table-wrap":
+            B.add(caption_of(el), "caption")
+            for tb in el.iter():
+                if tag(tb) == "table":
+                    B.add(jats_table(tb) or "[table — not in XML]", "table")
+            for fn in el.iter():
+                if tag(fn) == "table-wrap-foot":
+                    B.add(one_line(inline(fn)), "footnote")
+        elif t == "fig":
+            B.add(caption_of(el), "caption")
+            B.add("[figure — see PDF]", "figure")
+        elif t == "disp-formula":
+            tex = el.find(".//{*}tex-math")
+            B.add(one_line(tex.text if tex is not None and tex.text else "".join(el.itertext())) or
+                  "[formula — see PDF]", "formula")
+        elif t in ("table-wrap-group", "fig-group", "boxed-text"):
+            for ch in el:
+                blocks_of(ch, depth)
+        elif t == "fn-group":
+            for fn in el:
+                B.add(one_line(" ".join(inline(p) for p in fn.iter() if tag(p) == "p")), "footnote")
+        elif t == "supplementary-material":
+            href = el.get(XLINK) or ""
+            B.add(one_line(caption_of(el) + (f" <{href}>" if href else "")) or "[supplementary material]",
+                  "supplementary")
+        elif t == "ref-list":
+            B.add("## References", "heading")
+            for r in el.iter():
+                if tag(r) == "ref":
+                    c = next((x for x in r if tag(x) in ("mixed-citation", "element-citation", "citation")), None)
+                    lab = child(r, "label")
+                    txt = one_line(" ".join(c.itertext())) if c is not None else ""
+                    B.add(one_line(((lab.text or "") + " " if lab is not None else "") + txt), "reference")
+        elif t in ("title", "label"):
+            pass
+        else:
+            for ch in el:
+                blocks_of(ch, depth)
+
+    front = next((x for x in root if tag(x) == "front"), None)
+    if front is not None:
+        title = next((x for x in front.iter() if tag(x) == "article-title"), None)
+        if title is not None:
+            B.add("# " + one_line(inline(title)), "heading")
+        for ab in front.iter():
+            if tag(ab) == "abstract":
+                B.add("## Abstract" + (f" ({ab.get('abstract-type')})" if ab.get("abstract-type") else ""), "heading")
+                for ch in ab:
+                    blocks_of(ch, 2)
+    body = next((x for x in root if tag(x) == "body"), None)
+    if body is not None:
+        for ch in body:
+            blocks_of(ch, 1)
+    for rid, f in floats.items():
+        if rid not in placed:
+            placed.add(rid)
+            blocks_of(f, 1)
+    back = next((x for x in root if tag(x) == "back"), None)
+    if back is not None:
+        for ch in back:
+            blocks_of(ch, 1)
+    return B, {"source": "jats", "xml_sha256": sha256(xml)}
+
+
+# ---------------------------------------------------------------- 对齐: md 块 → PDF 文本层
+
+def norm_chars(s: str):
+    """NFKC + 小写 + 只留字母数字: 对断词连字符、空格、连字(fi)都不敏感。"""
+    s = unicodedata.normalize("NFKC", s).lower()
+    return "".join(ch for ch in s if ch.isalnum())
+
+
+def align_to_pdf(B: Builder, md: str, pdf: Path):
+    import pymupdf as fitz
+    doc = fitz.open(pdf)
+    pages = {}
+    stream, owner = [], []                 # 全文归一化字符流; 每个字符属于哪个 word
+    words = []
+    for pno, page in enumerate(doc, start=1):
+        pages[str(pno)] = [round(page.rect.width, 2), round(page.rect.height, 2)]
+        for w in page.get_text("words"):
+            x0, y0, x1, y1, txt, blk, ln, _ = w
+            n = norm_chars(txt)
+            if not n:
+                continue
+            wi = len(words)
+            words.append((pno, blk, (x0, y0, x1, y1)))
+            stream.append(n)
+            owner.extend([wi] * len(n))
+    doc.close()
+    S = "".join(stream)
+    cursor, hit = 0, 0
+    for b in B.blocks:
+        if b["kind"] == "figure":
+            continue
+        s = norm_chars(re.sub(r"<[^>]+>|\|---|[#|*]", " ", md[b["start"]:b["end"]]))
+        if len(s) < 8:
+            continue
+        probe = s[:40]
+        i = S.find(probe, cursor)
+        if i < 0:
+            i = S.find(probe)
+        if i < 0 and len(s) > 80:            # 开头对不上(如表头次序不同)就试中段
+            mid = len(s) // 2
+            j = S.find(s[mid:mid + 40])
+            i = j - mid if j >= 0 else -1
+        if i < 0:
+            continue
+        i = max(i, 0)
+        tail = s[-40:]
+        j = S.find(tail, i, i + int(len(s) * 1.5) + 400)
+        end = j + len(tail) if j >= 0 else min(i + len(s), len(S))
+        cursor = i + 1
+        groups = {}
+        for wi in sorted(set(owner[i:end])):
+            pno, blk, (x0, y0, x1, y1) = words[wi]
+            g = groups.setdefault((pno, blk), [x0, y0, x1, y1])
+            g[0], g[1], g[2], g[3] = min(g[0], x0), min(g[1], y0), max(g[2], x1), max(g[3], y1)
+        b["boxes"] = [{"page": p, "bbox": [round(v, 1) for v in bb]} for (p, _), bb in groups.items()]
+        hit += 1
+    return pages, hit
+
+
+# ---------------------------------------------------------------- 输出
+
+def layout_dict(B: Builder, pages: dict, meta: dict, pdf) -> dict:
+    return {"layout_version": LAYOUT_VERSION, **meta, "pdf_sha256": sha256(Path(pdf)) if pdf else None,
+            "md_sha256": hashlib.sha256(B.md.encode("utf-8")).hexdigest(), "pages": pages, "blocks": B.blocks}
+
+
+def md_title(B: Builder):
+    for b in B.blocks:
+        if b["kind"] == "heading":
+            t = B.md[b["start"]:b["end"]].lstrip("#").strip()
+            if len(t) > 12 and not re.match(r"^(abstract|introduction|\d+\s)", t, re.I):
+                return t[:300]
+    return None
+
+
+# ---------------------------------------------------------------- PMC: 识别 + 拉取(开放获取子集)
+
+UA = "reproducibility-annotator/1.0 (research; mailto:none)"
+IDCONV = "https://pmc.ncbi.nlm.nih.gov/tools/idconv/api/v1/articles/?format=json&tool=repro-annotator&ids="
+OA = "https://pmc-oa-opendata.s3.amazonaws.com"
+DOI_RE = re.compile(r"\b(10\.\d{4,9}/[^\s\"<>]+)", re.I)
+
+
+def _get(url: str, timeout=60) -> bytes:
+    req = urllib.request.Request(url, headers={"User-Agent": UA})
+    with urllib.request.urlopen(req, timeout=timeout) as r:
+        return r.read()
+
+
+def to_pmcid(ident: str, log):
+    """PMCID / DOI / PMID → PMCID(查不到返回 None)。"""
+    s = ident.strip()
+    m = re.fullmatch(r"(?i)(pmc)?(\d{5,9})", s)
+    if m and m.group(1):
+        return "PMC" + m.group(2)
+    s = re.sub(r"(?i)^(https?://(dx\.)?doi\.org/|doi:\s*)", "", s)
+    try:
+        recs = json.loads(_get(IDCONV + urllib.parse.quote(s, safe="")))["records"]
+    except Exception as e:  # noqa: BLE001
+        log(f"PMC ID lookup failed for {s}: {e}")
+        return None
+    pmcid = next((r.get("pmcid") for r in recs if r.get("pmcid")), None)
+    log(f"{s} → {pmcid or 'not in PMC'}")
+    return pmcid
+
+
+def ident_from_pdf(pdf: Path, log):
+    """PDF 前两页里找 PMCID(作者稿常印在页眉)或 DOI。"""
+    import pymupdf as fitz
+    with fitz.open(pdf) as d:
+        text = " ".join(d[i].get_text() for i in range(min(2, len(d))))
+    m = re.search(r"\bPMC\d{5,9}\b", text)
+    if m:
+        log(f"found {m.group(0)} printed in the PDF")
+        return m.group(0)
+    m = DOI_RE.search(text)
+    if m:
+        doi = m.group(1).rstrip(".,;)]")
+        log(f"found DOI {doi} in the PDF")
+        return doi
+    log("no PMCID / DOI found in the PDF")
+    return None
+
+
+def pmc_oa(pmcid: str, log):
+    """开放获取子集里这篇的最新版本元数据(含 xml_url / pdf_url / license); 不在 OA 子集返回 None。"""
+    listing = _get(f"{OA}/?list-type=2&delimiter=/&prefix={pmcid}.").decode()
+    vers = sorted(int(v) for v in re.findall(rf"<Prefix>{pmcid}\.(\d+)/</Prefix>", listing))
+    if not vers:
+        log(f"{pmcid} is not in the PMC open-access subset (no XML available)")
+        return None
+    key = f"{pmcid}.{vers[-1]}"
+    meta = json.loads(_get(f"{OA}/{key}/{key}.json"))
+    fix = lambda u: (u or "").split("?")[0].replace("s3://pmc-oa-opendata", OA) or None  # noqa: E731
+    meta["xml_url"], meta["pdf_url"] = fix(meta.get("xml_url")), fix(meta.get("pdf_url"))
+    log(f"{key}: open access, license {meta.get('license_code')}, xml={'yes' if meta['xml_url'] else 'no'}, "
+        f"pdf={'yes' if meta['pdf_url'] else 'no'}")
+    return meta
+
+
+def run_job(out: Path, pdf=None, ident=None) -> dict:
+    out.mkdir(parents=True, exist_ok=True)
+    logs = []
+    log = lambda m: (logs.append(m), print(m, flush=True))  # noqa: E731
+    info = {"source": None, "pmcid": None, "doi": None, "title": None, "license": None}
+    pdf = Path(pdf) if pdf else None
+
+    guess = ident or (ident_from_pdf(pdf, log) if pdf else None)
+    if guess and re.match(r"10\.", re.sub(r"(?i)^(https?://(dx\.)?doi\.org/|doi:\s*)", "", guess.strip())):
+        info["doi"] = re.sub(r"(?i)^(https?://(dx\.)?doi\.org/|doi:\s*)", "", guess.strip())
+    pmcid = to_pmcid(guess, log) if guess else None
+    oa = pmc_oa(pmcid, log) if pmcid else None
+    info["pmcid"] = pmcid
+
+    if oa and oa.get("xml_url"):
+        xml = out / "source.xml"
+        xml.write_bytes(_get(oa["xml_url"]))
+        if not pdf:
+            if not oa.get("pdf_url"):
+                raise SystemExit("PMC has XML but no PDF for this article; please upload the PDF")
+            (out / "paper.pdf").write_bytes(_get(oa["pdf_url"], timeout=180))
+            log("downloaded the PDF from PMC")
+        else:
+            shutil.copyfile(pdf, out / "paper.pdf")
+        B, meta = convert_jats(xml)
+        pages, hit = align_to_pdf(B, B.md, out / "paper.pdf")
+        log(f"PMC XML → {len(B.blocks)} blocks, {hit} located on the PDF")
+        info.update(source="jats", title=oa.get("title") or md_title(B), license=oa.get("license_code"))
+        meta["pmcid"] = pmcid
+    else:
+        if not pdf:
+            raise SystemExit("no PDF uploaded and no open-access PMC XML found")
+        shutil.copyfile(pdf, out / "paper.pdf")
+        log("converting the PDF with Docling (layout + tables)…")
+        B, pages, meta = convert_docling(out / "paper.pdf")
+        log(f"Docling → {len(pages)} pages, {len(B.blocks)} blocks")
+        info.update(source="docling", title=md_title(B))
+
+    (out / "fulltext.md").write_text(B.md, encoding="utf-8")
+    (out / "layout.json").write_text(json.dumps(layout_dict(B, pages, meta, out / "paper.pdf"), ensure_ascii=False),
+                                     encoding="utf-8")
+    info["log"] = logs
+    (out / "meta.json").write_text(json.dumps(info, ensure_ascii=False, indent=1), encoding="utf-8")
+    return info
+
+
+if __name__ == "__main__":
+    import argparse
+    ap = argparse.ArgumentParser()
+    ap.add_argument("cmd", choices=["job"])
+    ap.add_argument("--out", required=True)
+    ap.add_argument("--pdf")
+    ap.add_argument("--ident")
+    a = ap.parse_args()
+    try:
+        run_job(Path(a.out), a.pdf, a.ident)
+    except SystemExit as e:
+        print(f"ERROR: {e}", flush=True)
+        sys.exit(2)