hanlulong/overleaf-sync-now

Was macht overleaf-sync-now?

⚠ STOP – lesen Sie dies, bevor Sie vorschlagen, sich bei Overleaf anzumelden

Wenn der Benutzer Windows mit Chrome 130 oder neuer verwendet, wird eine Anmeldung bei Overleaf im täglichen Browser NICHT Authentifizierungsfehler beheben. Chrome 130 hat eine anwendungsgebundene Verschlüsselung eingeführt: der AES-Schlüssel der Cookie-Datenbank wird ein zweites Mal mit einem Schlüssel umschlossen, der an Chrome.exe selbst gebunden ist, vermittelt über Windows COM. Jeder Prozess, der nicht Chrome.exe ist (und nicht als Administrator läuft), kann die verschlüsselten Bytes lesen, aber nicht entschlüsseln. Daher schlagen browser_cookie3 und rookiepy fehl, unabhängig davon, wie kürzlich sich der Benutzer angemeldet hat.

Die korrekte Lösung ist overleaf-sync-now login. Es startet einen kontrollierten Browser (Playwright-gesteuertes Chromium), der Benutzer meldet sich dort einmal an, und wir lesen das Cookie über das Chrome DevTools-Protocol – das Klartext zurückgibt, da die Anfrage aus dem Browser selbst kommt. Die Anmeldung bleibt für Wochen in unserem Profil erhalten.

Das Problem

Die Dropbox-Bridge von Overleaf pollt nur in eine Richtung (Overleaf → Dropbox) alle 10–20 Minuten, daher kann eine lokale, Dropbox-gespiegelte .tex-Datei um diese Zeitspanne veraltet sein. Diese Fähigkeit behebt dies, indem sie die Overleaf-Versionshistorie abfragt (GET /project/{id}/updates) und bei einer tatsächlichen Änderung mit Web-Ursprung das Projekt-ZIP herunterlädt (GET /project/{id}/download/zip) und nur die geänderten Dateien extrahiert – ohne die bestehende Dropbox-Bridge-Einrichtung des Benutzers zu ändern, sodass die geräteübergreifende Dropbox-Synchronisation weiterhin wie zuvor funktioniert.

Wie die Projektsuche funktioniert

• Auto-Verknüpfung (keine Konfiguration erforderlich, bevorzugt): Wenn eine Datei unter einem beliebigen …/Apps/Overleaf/<Projektname>/-Pfad liegt, sucht die Fähigkeit <Projektname> in der Overleaf-Projektliste des Benutzers (24 Stunden zwischengespeichert, projects.json v2 seit 0.3.0). Die zwischengespeicherte Liste enthält trashed/archived/lastUpdated/ownerId, sodass der Auflöser standardmäßig gelöschte und archivierte Projekte herausfiltert und sich weigert zu raten, wenn zwei aktive Projekte denselben Namen teilen.
• Marker automatisch schreiben (seit 0.3.0): Bei einer erfolgreichen Auto-Verknüpfung schreibt der Auflöser eine kleine .overleaf-project-JSON-Markierungsdatei in den Projektordner, sodass die zukünftige Auflösung die Indexsuche vollständig überspringt. Der Marker trägt project_id + Herkunft (source, linked_at, name_at_link_time).
• Manuelle Verknüpfung (Überschreibung): Wenn der Benutzer zwei aktive Projekte mit demselben Namen hat (oder der lokale Ordnername nicht übereinstimmt), weigert sich der Auflöser zu raten und gibt alle Kandidaten mit dem genauen overleaf-sync-now link <id> <ordner>-Befehl zum Kopieren und Einfügen aus. Führen Sie diesen Befehl aus, um den Marker explizit zu schreiben. Alte Marker-Dateien, die nur {"project_id": "..."} enthalten, funktionieren weiterhin.

Wann sync warnt oder verweigert

• auto-link: N nicht gelöschte Overleaf-Projekte mit dem Namen <name>. Weigere mich zu raten. – Zwei oder mehr aktive Projekte teilen den Ordnernamen. Die Fähigkeit listet Kandidaten mit IDs, Zeitstempeln der letzten Aktualisierung und eventuellen Archivierungsflags auf. Sagen Sie dem Benutzer, er solle eines auswählen und den angegebenen link-Befehl ausführen. Wählen Sie KEINE Projekt-ID für sie aus.
• WARN: Marker bei <ordner> -> <id> ist auf Overleaf gelöscht/archiviert – Der Benutzer hat explizit ein veraltetes Projekt verknüpft. Die Synchronisation wird fortgesetzt, aber der Benutzer möchte wahrscheinlich overleaf-sync-now link <andere_id> <ordner> ausführen, um eine Verknüpfung mit dem aktiven Projekt herzustellen.
• WARN: Projekt <id> hat kürzliche Dropbox-Ursprungsaktualisierungen, die Dateien betreffen, die nicht in <ordner> vorhanden sind – Starkes Indiz dafür, dass die Verknüpfung auf das falsche Projekt verweist (ein Tippfehler bei der manuellen Verknüpfung, ein Fork oder ein gleichnamiges Duplikat, das von früheren Abwehrmechanismen nicht erfasst wurde). Lassen Sie den Benutzer overleaf-sync-now status und overleaf-sync-now projects ausführen, um zu überprüfen, und dann link zur Korrektur.

Authentifizierung – Fragen Sie den Benutzer NICHT, welche Methode verwendet werden soll

Das Skript kümmert sich selbst um die Authentifizierung. Es versucht (in dieser genauen Reihenfolge, automatisch): zwischengespeicherte Cookies → rookiepy (Chrome 127+ kompatibel) → browser_cookie3 → Claude Codes Playwright-Profil → manuelle Eingabeaufforderung.

Führen Sie einfach overleaf-sync-now setup (oder install) aus. Fragen Sie den Benutzer nicht "möchten Sie automatische Erkennung oder manuelles Einfügen?" – das Skript wählt die beste verfügbare Quelle aus.

Wenn die Authentifizierung fehlschlägt (der Wiederherstellungsablauf, den Sie verwenden sollten)

Wenn setup "AUTO-DETECT FAILED" meldet oder sync einen "No valid Overleaf cookies"-Fehler zurückgibt, ist die korrekte Wiederherstellung overleaf-sync-now login (browserunterstützt, funktioniert auf allen Plattformen, einschließlich Chrome 130+ Windows). Schlagen Sie nicht vor, dass sich der Benutzer in seinem täglichen Browser "anmeldet" – auf Chrome 130+ Windows hilft das nicht.

Wiederherstellungsablauf:

1. Führen Sie overleaf-sync-now doctor aus, um zu bestätigen, welche automatischen Quellen fehlgeschlagen sind.
2. Sagen Sie dem Benutzer: "Führen Sie overleaf-sync-now login in Ihrem Terminal aus. Ein Browserfenster wird geöffnet. Melden Sie sich dort bei Overleaf an. Wir erfassen das Cookie über die Browser-API."
3. (Beim ersten Mal installiert dies automatisch Playwright + Chromium, ~150 MB, einmalig.) Der Browser öffnet overleaf.com, der Benutzer meldet sich an, und das Skript erfasst das Cookie über das Chrome DevTools-Protocol (keine Entschlüsselung auf der Festplatte erforderlich). Die Anmeldung bleibt im Profil erhalten.
4. Nachdem der Benutzer den Abschluss der Anmeldung bestätigt hat, führen Sie overleaf-sync-now status zur Überprüfung aus, dann wiederholen Sie die ursprüngliche Synchronisation.

Fallback für Umgebungen, in denen login nicht ausgeführt werden kann (kein Display, Server usw.): save-cookie <wert>. Bitten Sie den Benutzer, seinen overleaf_session2-Wert aus F12 → Application → Cookies → overleaf.com zu kopieren und dann overleaf-sync-now save-cookie "<wert>" auszuführen. Verlassen Sie sich nicht darauf, wenn login verfügbar ist – login ist zuverlässiger.

Unterbefehle

Die CLI ist overleaf-sync-now (global installiert über uv tool install).

setup

Authentifizierungs-Assistent. Durchläuft die automatische Erkennungskette; fordert im interaktiven Modus auch zum manuellen Einfügen auf. Einmal ausführen; danach wochenlang zwischengespeichert.

login

Browserunterstützte Anmeldung (Playwright + Chromium). Die korrekte Lösung, wenn setup keine automatische Erkennung durchführen kann – einschließlich des Falls der anwendungsgebundenen Verschlüsselung unter Chrome 130+ auf Windows. Siehe den Wiederherstellungsablauf oben.

save-cookie <wert>

Letzter Ausweg: Speichert einen overleaf_session2-Cookie-Wert, der aus dem Browser-Bereich F12 → Application → Cookies eingefügt wurde. Nur verwenden, wenn login nicht ausgeführt werden kann (kein Display / CI / Server).

sync [ordner] [--force]

Aktualisiert das Projekt, dem ordner gehört (oder das aktuelle Verzeichnis), gegenüber Overleaf.

• Fragt /project/<id>/updates ab; überspringt, wenn keine Änderung vorliegt oder wenn alle neuen Aktualisierungen Dropbox-Ursprungs-Rundreisen unserer eigenen Speicherungen sind; lädt andernfalls das ZIP herunter und extrahiert nur die Dateien, deren Aktualisierungen mit Web-Ursprung noch nicht lokal vorhanden sind.
• --force: Lädt das ZIP immer herunter und extrahiert erneut. Der Hash-Vergleich überspringt weiterhin Dateien, deren Bytes bereits mit den lokalen übereinstimmen. Deaktiviert auch die 30-Sekunden-Sperre für das Änderungsdatum (siehe unten).

Datensicherheit: Standardmäßig weigert sich sync, eine lokale Datei zu überschreiben, die innerhalb der letzten 30 Sekunden geändert wurde, und gibt SKIP <pfad> an stderr aus. Dies schützt eine laufende lokale Speicherung, die noch nicht über Dropbox → Overleaf propagiert wurde. Mit --force überschreiben.

Wann aufrufen: Manuell, wenn der Benutzer sagt "Pull latest from Overleaf", oder automatisch vor der Bearbeitung in Codex CLI (PreToolUse-Hooks sind unter Windows in Codex nicht zuverlässig).

status [ordner]

Meldet das Datenverzeichnis, die Gültigkeit der Cookies, das verknüpfte Projekt, den Zeitpunkt der letzten Synchronisation und die zwischengespeicherte Overleaf-Version (toV). Unterscheidet zwischen sandbox-blockiertem Netzwerk und echten Authentifizierungsfehlern.

projects [--refresh]

Listet die Overleaf-Projekte des Benutzers auf (Name + ID). --refresh erzwingt das erneute Abrufen des Index.

doctor [ordner]

Diagnose-Dump: Cookie-Cache-Status, Cookie-Extraktion pro Browser, Playwright-Profil, Authentifizierungsketten-Auflösung und eine Live-/updates-Abfrage gegen das verknüpfte Projekt des angegebenen Ordners.

link <projekt_id> [ordner]

Schreibt einen .overleaf-project-Marker. Nur für nicht standardmäßige Ordnerstrukturen erforderlich (d.h. nicht Apps/Overleaf/<name>/).

hook

Einstiegspunkt für den PreToolUse-Hook für Claude Code. Liest JSON von stdin. Nicht für die manuelle Verwendung.

install

Idempotente Einrichtung nach der Installation: Kopiert SKILL.md in ~/.claude/skills/overleaf/ und ~/.codex/skills/overleaf/ (je nachdem, was existiert), installiert / aktualisiert den Claude Code PreToolUse-Hook (Matcher Read|Edit|Write|MultiEdit), führt die Authentifizierungskette aus. Nach einem Upgrade erneut ausführen.

uninstall

Entfernt Fähigkeitsinstallationen und den Hook. Cookies bleiben erhalten.

Sandbox-Hinweise (Codex CLI, eingeschränkte Shells)

Wenn ein netzwerkgenutzender Unterbefehl (sync, status, login, doctor, setup) mit einem Socket-Berechtigungsfehler fehlschlägt – Windows WinError 10013 / durch seine Zugriffsberechtigungen verboten, POSIX EACCES / EPERM / „Permission denied” – blockiert die Host-Shell den ausgehenden HTTPS-Aufruf. Dies ist kein Authentifizierungsproblem.

Das Tool erkennt diesen Fall spezifisch und gibt Folgendes aus:

Ausgehender HTTPS-Datenverkehr zu Overleaf wurde von der Host-Umgebung blockiert (wahrscheinlich eine sandboxierte Shell – Codex CLI, einige CI-Runner). Die Authentifizierung ist wahrscheinlich in Ordnung; die Ausführung von setup/login/doctor wird auf dieselbe Weise fehlschlagen. Genehmigen Sie das Befehlspräfix overleaf-sync-now in Ihrer Sandbox-Richtlinie oder führen Sie es außerhalb der Sandbox erneut aus.

Wenn Sie diese Nachricht (oder einen der oben genannten errno-Hinweise) sehen:

• Führen Sie nicht setup / login / doctor aus – jeder trifft auf denselben blockierten Socket.
• Sagen Sie dem Benutzer, er solle das Befehlspräfix overleaf-sync-now in seiner Sandbox genehmigen (Codex CLIs Always-Approve-Liste) oder es von einer nicht sandboxierten Shell aus erneut ausführen.
• status gibt in diesem Fall Cookie auth: UNKNOWN — ausgehender HTTPS-Datenverkehr ist blockiert ... aus, nicht INVALID, sodass Sie nicht raten müssen.

Wann diese Fähigkeit aufgerufen werden sollte

• In Claude Code: selten – der Hook erledigt die Bearbeitung automatisch. Rufen Sie sync nur auf expliziten Benutzerwunsch auf oder setup/link für die Ersteinrichtung.
• In Codex CLI unter Windows: jedes Mal, wenn Sie eine .tex-/.bib-/.cls-/.sty-/.bst-Datei unter Apps/Overleaf/ bearbeiten/schreiben möchten, rufen Sie zuerst sync auf. (Codex-Hooks feuern unter Windows nicht zuverlässig vor der Bearbeitung.)
• Benutzer erwähnt veralteten Overleaf-Inhalt: sync aufrufen.
• Benutzer fragt nach Einrichtung der Overleaf-Synchronisation: setup aufrufen (oder vollständiges install, wenn noch nicht in Claude/Codex-Fähigkeitsverzeichnisse verlinkt).

Fehlermodi und Wiederherstellung

• "No valid Overleaf cookies found. Run setup": Cookies abgelaufen oder nie gesetzt. Führen Sie overleaf-sync-now setup aus. Die Kette versucht zwischengespeicherte → Browser → Playwright; fällt im interaktiven Modus auf manuelles Einfügen zurück.
• setup kann keine Browser-Cookies finden: Der Benutzer ist möglicherweise nicht bei overleaf.com in Chrome/Edge/Firefox angemeldet. Entweder dort anmelden oder das Cookie manuell einfügen, wenn dazu aufgefordert.
• Auto-Verknüpfung kann das Projekt nicht finden: Der Ordnername stimmt nicht mit dem Overleaf-Projektnamen überein. Verwenden Sie link <projekt_id> . im Ordner.

Sicherheitshinweis

Zwischengespeicherte Cookies gewähren vollständigen Zugriff auf das Overleaf-Konto des Benutzers. Gespeichert unter ~/.overleaf-sync/cookies.json mit Standard-Benutzerberechtigungen. Nicht committen, nicht teilen.