前言¶
在 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 等文档。
