前言¶
在 DeepSeek Harness（DSH）裏寫論文或改 LaTeX，常見做法是本地用 Agent 改文件，協作仍放在 Overleaf 網頁上。若只靠手動下載 zip 或依賴 Overleaf 付費 Git 橋接，Agent 很難穩定地 pull、push、看 diff。下面介紹社區插件 dsh-overleaf-sync（維護者 measureer）：它把本地 LaTeX 目錄與 Overleaf 項目綁在一起，通過 Overleaf 編輯器自帶的協作通道（Socket.IO + OT）同步，不走 Git 橋接；拉取後可自動 git init，並支持後臺 watch 與衝突處理。
這是什麼¶
dsh-overleaf-sync 是 DSH 的 Cordis 插件，分類爲聯網工具。一句話：在 Harness 裏爲 Agent 提供 overleaf_pull / overleaf_push / overleaf_diff 等工具，以及設置頁與右側邊欄，把本地文件夾與 Overleaf 項目雙向同步。思路參照 VS Code 擴展 measureer/overleaf-sync。README 標明當前階段爲 M3 完成（登錄、綁定、拉取、推送、三方 diff、watch、衝突解決與 GUI 兩半均已落地）。
- 目錄頁：https://www.skillhub.cn/plugins/measureer/dsh-overleaf-sync
- 源碼：https://github.com/measureer/dsh-overleaf-sync
- 許可證：MIT（見
package.json） - DSH 引擎要求：
dsh >= 0.1.7-rc.1；Node>= 22
核心功能¶
Agent 工具¶
插件向 DSH 註冊一組只讀或寫遠端/本地的工具（推送默認 dry-run，需顯式關閉纔會寫遠端）：
| 工具 | 作用 | 是否寫遠端/本地 |
|---|---|---|
overleaf_status |
登錄態、綁定、文件數、git、watch | 否 |
overleaf_login / overleaf_logout |
保存或清除 cookie/CSRF | 本地憑據 |
overleaf_projects |
列出可見項目 | 否 |
overleaf_link |
綁定項目與本地目錄，寫 link.json |
本地 |
overleaf_pull |
遠端 → 本地；首次成功可自動建 git | 本地文件 |
overleaf_push |
本地 → 遠端（默認 dry-run） | 遠端 |
overleaf_diff |
local / baseline / remote 三方對比 | 否 |
overleaf_watch |
後臺雙向同步 on/off/status | 兩端 |
overleaf_conflicts / overleaf_resolve |
列衝突；keep_local / keep_remote / merge |
兩端 |
默認行爲（可配置）¶
- 未指定
localRoot時，拉取目錄默認爲~/Overleaf/<項目名>（配置鍵localRootPattern）。 - 拉取後默認 自動
git init並首次提交（git.autoInit；若已在上層 git 倉庫內則複用，不嵌套）。 - 衝突 不靜默覆蓋：本地保留，遠端側寫入
foo.remote-<ts>.tex等（defaultStrategy）。 - 後臺 watch 默認關閉（
watch.autoStart爲真時插件加載即啓動）。
GUI¶
具備 DSH Web 宿主時，提供：
- 設置頁（Settings → Overleaf 同步）：Cookie/CSRF、選項目、綁定目錄、策略與 git/watch 開關。
- 右側邊欄 tab：狀態、待推送、Pull/Push、watch 開關、衝突逐條解決、日誌與 SSE 刷新。
Host 側暴露 /overleaf/api/* 與 GET /overleaf/events；無 webServer 時退化爲純工具插件。
自建 Overleaf 實例¶
baseUrl 默認 https://www.overleaf.com，可在登錄或設置裏改爲 CE / Server Pro 等地址；支持 Cookie 透傳、子路徑部署、socket 協議探測（含部分 0.9 老實例）。登錄仍須從瀏覽器複製 Cookie，插件 不收密碼。
憑據與 link.json 等落在 ~/.dsh/overleaf-sync/，不寫進項目目錄。
安裝與啓用¶
官方 README 給出的安裝方式如下（Release 的 tgz；npm 包發佈中見倉庫 RELEASING.md）：
# 從 GitHub Release 的 tgz 安裝
dsh plugin add ./dsh-overleaf-sync-0.1.0.tgz
# 或
dsh plugin --profile desktop add <absolute-path>.tgz
本地開發可 link 進 profile（改代碼後需重啓 DSH）：
dsh plugin --profile desktop add link:C:/code/dsh-overleaf-sync
等價手工步驟：在 profile 的 package.json 增加依賴並在 dsh.profile.bundles 追加包名，於 profile 目錄執行 pnpm install 後重啓 DSH。默認配置在插件 cordis.patch.yml，可在 profile 的同名文件中 整體替換 覆蓋。
安裝前請自行查看源碼與 MIT 許可證；插件以當前 DSH 進程權限訪問網絡與本地文件，僅安裝你信任的來源。
典型用法¶
README 推薦的 Agent 流程如下。
- 瀏覽器登錄 Overleaf，在 DevTools 複製
Cookie（含overleaf_session2=…）與頁面<meta name="ol-csrfToken">的值。 - 調用
overleaf_login粘貼上述兩項（無密碼字段）。 overleaf_projects查項目 id。overleaf_link綁定；不傳localRoot時使用~/Overleaf/<項目名>。overleaf_pull下載全部文檔，並按配置自動git init+ 首次提交。- 本地修改後
overleaf_diff確認變更，再overleaf_push：先默認 dry-run，確認無誤後傳dryRun: false寫遠端。
需要持續同步時，可在側邊欄或 overleaf_watch 開啓後臺雙向同步；出現衝突用 overleaf_conflicts 與 overleaf_resolve 處理。同一項目同一賬號僅允許一條活動 watch 連接；部分自建實例與瀏覽器同開一項目時會爭用 socket，需先關閉瀏覽器標籤。
適用場景與注意¶
適合：在 DSH 裏用 Agent 改本地 LaTeX，同時與 Overleaf 網頁協作、又不想依賴 Git 橋接的用戶；需要 diff、dry-run 推送與衝突顯式策略的論文寫作流程。
注意：
- 憑據來自瀏覽器 Cookie，需自行保管；日誌對 session 做脫敏，但仍應限制 profile 與機器訪問權限。
- 寫遠端前務必理解 默認 dry-run 與衝突不覆蓋策略。
- 社區目錄 SkillHub 與 DeepSeek / 幻方無官方從屬關係；DSH 生態理念是「一切皆插件」，本文事實以 GitHub README 與倉庫文檔爲準。
結尾¶
dsh-overleaf-sync 把 Overleaf 項目同步能力收進 DSH 工具與 GUI，讓 Agent 能按步驟 pull、diff、再 push，並在本地保留 git 歷史。進一步瞭解實現與 API 契約可見倉庫 docs/design.md 等文檔。
