overleaf-sync

Overleaf Sync

将本地论文目录与 Overleaf 项目连接起来，以便：

• 你可以继续在 Overleaf 网页界面中编辑（或与协作者共享编辑权限）
• ARIS可以读取你的更改、运行审计（/paper-claim-audit、/citation-audit、/auto-paper-improvement-loop），并将修复推回

此功能使用官方的Overleaf Git bridge（Premium 功能）。Agent 永远不会看到你的身份验证令牌——你只需手动完成一次性身份验证，这样令牌就会保存在 macOS 钥匙串中，而不会出现在聊天记录或 .git/config 中。

何时使用此技能

• 你想使用 Overleaf 作为编辑界面（协作体验更好，可与团队共享），同时仍在本地运行 ARIS 工作流
• 你想将现有的本地 ARIS 论文推送到 Overleaf，供合作者编辑
• 协作者在 Overleaf 中进行了更改，你想先拉取并查看差异，再继续本地工作

常量

• CLONE_DIR_DEFAULT = paper-overleaf（与现有的 paper/ 同级，而非位于 paper/ 内）
• CREDENTIAL_HELPER = osxkeychain（macOS）/ manager（Windows）/ cache（Linux 回退选项）
• TOKEN_HANDLING = 绝不将令牌写入磁盘、环境变量或聊天内容。 用户只需在终端凭据提示中粘贴一次；之后由操作系统钥匙串保存。

架构

┌─────────────────┐       git pull/push      ┌─────────────────┐
│  Local paper/   │ ◄─── rsync ──── ►       │ paper-overleaf/ │ ◄──► Overleaf web
│  (ARIS audits)  │                          │ (git bridge)    │     (collaborators)
└─────────────────┘                          └─────────────────┘

paper-overleaf/ 目录是 Overleaf 项目的 git 克隆。paper/ 目录是 ARIS 技能运行时使用的工作副本。两者通过 rsync 保持同步。

单一事实来源规则：在任意时刻，将其中一个目录视为当前编辑内容的权威来源。使用 pull 或 push 明确切换方向，并在切换前运行 status 检查，以发现意外差异。

子命令

setup <project-id> — 一次性设置

为新的 Overleaf 项目设置连接。用户必须在自己的终端中运行此命令，绝不能通过 Agent 运行。 此技能附带一个经过加固的设置脚本，该脚本会：

1. 除非 stdin/stdout 是 TTY，否则拒绝运行（不会在 Agent 执行环境中运行）
2. 从隐藏提示中读取令牌（不会进入聊天记录或 shell 历史）
3. 克隆后立即从远程 URL 中移除令牌
4. 初始化操作系统钥匙串，以便之后 Agent 执行操作时无需身份验证
5. 自动在 paper-overleaf/.git/hooks/ 中安装 pre-commit 挂钩，拒绝提交任何包含令牌模式 olp_[A-Za-z0-9]{20,} 的 blob——这是硬性技术限制，而非行为规则

Agent 在此处唯一需要做的事是打印给用户的指令：

Run this in your own terminal (NOT through me):

    bash <ARIS_REPO>/tools/overleaf_setup.sh <project-id-or-url>

When it finishes, tell me "setup done" and I'll verify.

用户报告“setup done”后，Agent 会验证（不涉及令牌）：

cd paper-overleaf
git remote -v                    # must show URL WITHOUT token
git config --get credential.helper
git fetch && git log --oneline -3   # must succeed without prompting
ls .git/hooks/pre-commit         # must exist
bash <ARIS_REPO>/tools/overleaf_audit.sh .   # must report "Audit clean"

如果 paper-overleaf/ 已存在但为空（新的 Overleaf 项目），Agent 接下来会将本地 paper/ 镜像到其中（见 push 工作流）。

pull — 每次编辑会话前

cd paper-overleaf && git pull --ff-only

# Show what changed since last pull
LAST=$(git rev-parse HEAD@{1})
git diff --stat $LAST..HEAD
git diff $LAST..HEAD -- 'sec/*.tex'        # detailed view for prose changes

差异处理规范——切勿盲目合并到本地 paper/。 Overleaf 编辑经常包含：

• 未写完的句子（协作者在思路未完成时点击了保存）
• 规范参考资料中没有的拼写错误（例如将 Large 拼成 Lrage）
• 被注释掉的代码块，可能是有意为之，也可能是临时保存的内容
• 数字更改，应重新触发 /paper-claim-audit
• 引用键更改，应重新触发 /citation-audit

对于每个差异块，选择以下一种操作：

差异块特征	操作
无问题的编辑改进	同步到 paper/，无需审计
数值 / 论断更改	同步，然后重新运行 /paper-claim-audit
新增 \cite{...}	同步，然后重新运行 /citation-audit
未写完的句子 / 明显的拼写错误	标记给用户，切勿自动同步
新增章节 / 重新组织结构	停止操作，先询问用户再同步

逐个差异块完成判断后：

# Sync only the files the user approved into local paper/
rsync -av paper-overleaf/sec/0.abstract.tex paper/sec/0.abstract.tex
# (or use Edit tool for surgical changes that skip half-sentences)

push — 本地编辑后

在 ARIS 技能编辑了 paper/，并且你希望 Overleaf 上的协作者看到更改后使用。

# 1. Always pull first to surface remote drift
cd paper-overleaf && git pull --ff-only

# 2. If pull was a no-op, sync local paper → paper-overleaf
rsync -av --delete \
  --exclude='.git' --exclude='.DS_Store' \
  --exclude='*.aux' --exclude='*.log' --exclude='*.bbl' --exclude='*.blg' \
  --exclude='*.fls' --exclude='*.fdb_latexmk' --exclude='*.out' \
  --exclude='*.synctex.gz' --exclude='*.toc' \
  paper/ paper-overleaf/

# 3. Show what would be pushed
git status --short
git diff --stat

# 4. Commit + push
git add -A
git commit -m "<descriptive message — what ARIS changed and why>"
git push

提交消息规范：注明生成更改的 ARIS 技能，方便 Overleaf 上的协作者了解来源。示例：

• paper-write: regenerated sec/3.assurance after audit cascade refactor
• citation-audit: fix 14 metadata entries (madaan2023, lee2024, ...)
• paper-claim-audit: correct sec/5 numbers vs results/run_2026_04_19.json

确认关卡：push 会写入共享资源。在运行 git push 前，务必向用户展示 git diff --stat（如果有文本更改，还要展示一段有代表性的差异）。除非用户事先说明 auto: true，否则应等待用户明确确认。

status — 诊断

cd paper-overleaf
git fetch
echo "=== Remote-vs-local divergence ==="
git log --oneline HEAD..origin/master    # remote ahead
git log --oneline origin/master..HEAD    # local ahead
echo "=== paper/ vs paper-overleaf/ divergence ==="
diff -rq --brief paper/ paper-overleaf/ 2>/dev/null \
  | grep -v "Only in paper/.*\.\(aux\|log\|out\|fls\|fdb_latexmk\|bbl\|blg\|synctex\|toc\)" \
  | grep -v "Only in paper-overleaf/.git" \
  | grep -v "DS_Store"

三方状态评估：

远程是否有新提交？	paper/ 与 paper-overleaf/ 是否存在差异？	含义	建议操作
否	否	干净	无需操作
是	否	Overleaf 有新编辑	运行 pull，然后重新运行 status
否	是	本地 ARIS 编辑尚未同步	运行 push
是	是	已分叉 — 需要合并	停止操作，告知用户，切勿自动解决

冲突解决

如果 git pull --ff-only 因真正的分叉而失败：

1. 不要运行 git pull（这会自动合并）。
2. 不要运行 git reset --hard 或 git push --force（会造成破坏）。
3. 向用户展示 git log origin/master ^HEAD（他们在 Overleaf 上的提交）和 git log HEAD ^origin/master（本地 ARIS 提交）。
4. 询问用户每个文件应保留哪一方的内容，或者让他们在 Overleaf 中手动合并，然后再重新拉取。

令牌安全 — 深度防御

仅靠行为规则还不够——下一个读取此技能的 Agent 可能会忘记这些规则。因此，此技能依赖于技术防护措施，即使 Agent 行为不当，这些措施仍然有效：

层级	防护措施	强制执行位置
1. 设置	overleaf_setup.sh 拒绝在没有交互式 TTY 的情况下运行（Agent 没有 TTY）	tools/overleaf_setup.sh
2. 输入	通过 read -s 读取令牌（隐藏提示，不进入 shell 历史记录，也绝不会进入聊天）	tools/overleaf_setup.sh
3. 存储	令牌通过 git credential approve 直接存入操作系统密钥链；远程 URL 会被移除令牌	tools/overleaf_setup.sh
4. 提交	paper-overleaf/.git/hooks/pre-commit 会使用 grep 检查暂存内容中的 olp_[A-Za-z0-9]{20,}，并在发现时中止	由设置脚本自动安装
5. 审计	overleaf_audit.sh 会扫描工作树、远程 URL、Git 历史记录和凭据文件	tools/overleaf_audit.sh

行为规则（仍然适用，但优先级较低）：

• 绝不要让用户把令牌粘贴到聊天中。如果用户还是这样做了：(a) 表示已收到；(b) 告知他们前往 https://www.overleaf.com/user/settings 撤销令牌；(c) 如果密钥链已预先配置，则通过密钥链恢复。
• 绝不要将令牌写入提交到任何仓库的文件（如 .env、.netrc、tools/*.sh 等）。
• 绝不要在 git remote -v URL 中包含令牌——克隆后应将其移除。
• 如果 push/pull 返回 401 Unauthorized，告知用户密钥链中的条目已过期，并让他们重新运行 overleaf_setup.sh。不要索要新令牌。

互斥规则

双向同步中最主要的问题来源，就是两端同时编辑。

• 如果用户正在 Overleaf 中编辑，ARIS 技能应以只读方式访问 paper/，直到用户运行 /overleaf-sync pull。
• 如果 ARIS 正在执行 /auto-paper-improvement-loop 或 /paper-write，用户应暂停在 Overleaf 中编辑，直到循环完成并运行 /overleaf-sync push。

如有疑问，先运行 status。

输出约定

• 仓库根目录下的 paper-overleaf/ 目录，是 Overleaf 项目的 git clone（origin URL 不含 token）
• paper/ 目录的用途保持不变——仍是 ARIS 工作副本
• 每次 pull/push 操作：向用户返回一行摘要（拉取/推送的提交、文件数量、Overleaf 项目 URL 链接）

另请参阅

• /paper-claim-audit — 拉取涉及数字的 Overleaf 更改后重新运行
• /citation-audit — 拉取新增/编辑 \cite{...} 的 Overleaf 更改后重新运行
• /paper-compile — 本地 LaTeX 构建；Overleaf 在云端独立编译
• Overleaf Git bridge 文档：https://www.overleaf.com/learn/how-to/Using_Git_and_GitHub