overleaf-sync

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Overleaf Sync

Overleaf 同步

Bridge a local paper directory with an Overleaf project so that:

You can keep editing in the Overleaf web UI (or share editing access with collaborators)
ARIS can read your changes, run audits (
```
/paper-claim-audit
```
,
```
/citation-audit
```
,
```
/auto-paper-improvement-loop
```
), and push fixes back

This uses the official Overleaf Git bridge (Premium feature). The agent never sees your authentication token — you do the one-time auth manually so the token lives in macOS Keychain, not in chat history or

.git/config

将本地论文目录与Overleaf项目桥接，实现：

你可以继续在Overleaf网页端编辑（或与协作者共享编辑权限）
ARIS可以读取你的更改，运行审核（
```
/paper-claim-audit
```
、
```
/citation-audit
```
、
```
/auto-paper-improvement-loop
```
），并推送修复内容

此功能使用官方Overleaf Git桥接（高级功能）。Agent绝不会接触你的身份验证令牌——你手动完成一次性身份验证，令牌将存储在macOS钥匙串中，不会出现在聊天记录或

.git/config

里。

When to Use This Skill

何时使用此技能

You want to use Overleaf as the editing surface (better collaboration, shared with team) but still run ARIS pipelines locally
You want to take an existing local ARIS paper and push it to Overleaf for a co-author to edit
A collaborator made changes in Overleaf and you want to pull + diff them before continuing local work

你希望将Overleaf作为编辑界面（协作性更强，可与团队共享），但仍在本地运行ARIS流水线
你希望将现有的本地ARIS论文推送到Overleaf，供合著者编辑
协作者在Overleaf中进行了更改，你希望在继续本地工作前拉取并对比差异

Constants

常量

CLONE_DIR_DEFAULT =
```
paper-overleaf
```
(sibling of existing
```
paper/
```
, NOT inside
```
paper/
```
)
CREDENTIAL_HELPER =
```
osxkeychain
```
(macOS) /
```
manager
```
(Windows) /
```
cache
```
(Linux fallback)
TOKEN_HANDLING = NEVER write token to disk, env var, or chat. User pastes it once into the terminal credential prompt; the OS keychain stores it from then on.

CLONE_DIR_DEFAULT =
```
paper-overleaf
```
（与现有
```
paper/
```
同级，而非在
```
paper/
```
内部）
CREDENTIAL_HELPER =
```
osxkeychain
```
（macOS）/
```
manager
```
（Windows）/
```
cache
```
（Linux备用）
TOKEN_HANDLING = 绝不将令牌写入磁盘、环境变量或聊天记录。用户在终端凭据提示中粘贴一次令牌；此后由操作系统钥匙串存储。

Architecture

架构

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

The

paper-overleaf/

directory is a git clone of the Overleaf project. The

paper/

directory is the working copy where ARIS skills run. They are kept in sync via

rsync

Single-source-of-truth rule: at any given time, treat one of them as authoritative for active editing. Switch directions explicitly with

pull

push

, and run a

status

check before either to surface unexpected divergence.

┌─────────────────┐       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

检查，以发现意外的分歧。

Sub-commands

子命令

setup <project-id>

— one-time

setup <project-id>

— 一次性操作

Sets up the bridge for a new Overleaf project. The user runs this in their own terminal, never through the agent. The skill ships with a hardened setup script that:

Refuses to run unless stdin/stdout are a TTY (won't run inside an agent harness)
Reads the token from a hidden prompt (no chat history, no shell history)
Strips the token from the remote URL immediately after cloning
Primes the OS keychain so subsequent agent operations are auth-free
Auto-installs a
pre-commit
hook in
paper-overleaf/.git/hooks/
that refuses to commit any blob containing the token pattern
olp_[A-Za-z0-9]{20,}
— a hard technical block, not a behavioral rule

The agent's only role here is to print the user instruction:

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.

After the user reports "setup done", the agent verifies (token-free):

bash

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/

exists but is empty (new Overleaf project), the agent then mirrors local

paper/

into it (see

push

workflow).

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

除非标准输入/输出为TTY，否则拒绝运行（不会在Agent环境中运行）
从隐藏提示中读取令牌（不会出现在聊天记录或Shell历史中）
克隆完成后立即从远程URL中移除令牌
初始化操作系统钥匙串，以便后续Agent操作无需身份验证
自动在
paper-overleaf/.git/hooks/
中安装
pre-commit
钩子，拒绝提交任何包含
olp_[A-Za-z0-9]{20,}
令牌格式的Blob——这是一个硬性技术限制，而非行为规则

Agent的唯一作用是打印用户指令：

在你自己的终端中运行此命令（不要通过我）：

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

完成后告诉我“setup done”，我会进行验证。

用户报告“setup done”后，Agent将进行无令牌验证：

bash

cd paper-overleaf
git remote -v                    # 必须显示不含令牌的URL
git config --get credential.helper
git fetch && git log --oneline -3   # 必须无需提示即可成功运行
ls .git/hooks/pre-commit         # 必须存在
bash <ARIS_REPO>/tools/overleaf_audit.sh .   # 必须报告“Audit clean”

如果

paper-overleaf/

已存在但为空（新Overleaf项目），Agent会将本地

paper/

镜像到其中（见

push

工作流）。

pull

— before each editing session

pull

— 每次编辑会话前

bash

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

bash

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


**Diff protocol — DO NOT blindly merge into local `paper/`.** Overleaf edits frequently include:

- **Half-finished sentences** (collaborator clicked save mid-thought)
- **Typos** that aren't in canonical references (`Lrage` for `Large`)
- **Commented-out blocks** that may be intentional or may be a stash
- **Number changes** that should re-trigger `/paper-claim-audit`
- **Cite key changes** that should re-trigger `/citation-audit`

For each diff hunk, decide one of:

| Hunk character | Action |
|----------------|--------|
| Clean editorial improvement | Sync into `paper/`, no audit needed |
| Numerical / claim change | Sync, then re-run `/paper-claim-audit` |
| New `\cite{...}` | Sync, then re-run `/citation-audit` |
| Half-sentence / obvious typo | Flag to user, do NOT auto-sync |
| New section / restructure | Stop, ask user before syncing |

After deciding per-hunk:

```bash

LAST=$(git rev-parse HEAD@{1}) git diff --stat $LAST..HEAD git diff $LAST..HEAD -- 'sec/*.tex' # 针对文本更改的详细视图


**差异协议——不要盲目合并到本地`paper/`中**。Overleaf编辑通常包含：

- **未完成的句子**（协作者在思考中途点击了保存）
- **拼写错误**（与标准引用不符，如`Lrage`应为`Large`）
- **被注释掉的代码块**可能是有意为之，也可能是暂存内容
- **数值更改**应重新触发`/paper-claim-audit`
- **引用键更改**应重新触发`/citation-audit`

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

| 差异块特征 | 操作 |
|----------------|--------|
| 清晰的编辑改进 | 同步到`paper/`，无需审核 |
| 数值/声明更改 | 同步，然后重新运行`/paper-claim-audit` |
| 新增`\cite{...}` | 同步，然后重新运行`/citation-audit` |
| 未完成句子/明显拼写错误 | 标记给用户，不要自动同步 |
| 新增章节/结构调整 | 停止操作，询问用户后再同步 |

确定每个差异块的操作后：

```bash

Sync only the files the user approved into local paper/

仅将用户批准的文件同步到本地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)

（或使用编辑工具进行精准更改，跳过未完成的句子）

undefined

undefined

push

— after local editing

push

— 本地编辑完成后

Use after ARIS skills have edited

paper/

and you want collaborators on Overleaf to see the changes.

bash

undefined

在ARIS技能编辑完

paper/

，且你希望Overleaf上的协作者看到更改时使用。

bash

undefined

1. Always pull first to surface remote drift

1. 始终先拉取以发现远程变更

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

2. If pull was a no-op, sync local paper → paper-overleaf

2. 如果拉取无变更，将本地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

3. 显示即将推送的内容

git status --short git diff --stat

4. Commit + push

4. 提交并推送

git add -A git commit -m "<descriptive message — what ARIS changed and why>" git push


**Commit message protocol**: include the ARIS skill that produced the change so collaborators on Overleaf understand provenance. Examples:

- `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`

**Confirmation gate**: `push` writes to a shared resource. ALWAYS show the user `git diff --stat` (and a representative hunk for prose changes) before running `git push`. Wait for explicit confirmation unless the user said `auto: true` upfront.

git add -A git commit -m "<描述性信息——ARIS更改了什么以及原因>" 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

— diagnostic

status

— 诊断

bash

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"

Three-way state assessment:

Remote ahead?	paper/ vs paper-overleaf/ differ?	Meaning	Recommended action
No	No	Clean	Nothing to do
Yes	No	Overleaf has new edits	Run `pull` , then re-run status
No	Yes	Local ARIS edits unsynced	Run `push`
Yes	Yes	Diverged — needs merge	Stop, surface to user, do NOT auto-resolve

bash

cd paper-overleaf
git fetch
echo "=== 远程与本地差异 ==="
git log --oneline HEAD..origin/master    # 远程领先
git log --oneline origin/master..HEAD    # 本地领先
echo "=== paper/ 与 paper-overleaf/ 差异 ==="
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`
是	是	已分歧——需要合并	停止操作，告知用户，不要自动解决

Conflict Resolution

冲突解决

git pull --ff-only

fails because of true divergence:

Do not run
```
git pull
```
(which would auto-merge).
Do not run
```
git reset --hard
```
or
```
git push --force
```
(destructive).
Show the user
```
git log origin/master ^HEAD
```
(their Overleaf commits) and
```
git log HEAD ^origin/master
```
(local ARIS commits).
Ask the user which side to take per file, or to manually merge in Overleaf and then re-pull.

如果

git pull --ff-only

因真实分歧而失败：

不要运行
```
git pull
```
（会自动合并）。
不要运行
```
git reset --hard
```
或
```
git push --force
```
（具有破坏性）。
向用户展示
```
git log origin/master ^HEAD
```
（他们在Overleaf的提交）和
```
git log HEAD ^origin/master
```
（本地ARIS的提交）。
询问用户每个文件应保留哪一侧的内容，或让用户在Overleaf中手动合并后重新拉取。

Token Security — Defense in Depth

令牌安全——深度防御

Behavioral rules alone are not enough — the next agent reading this skill might forget them. The skill therefore relies on technical guards that hold even if the agent misbehaves:

Layer	Guard	Where enforced
1. Setup	`overleaf_setup.sh` refuses to run without an interactive TTY (agents don't have one)	`tools/overleaf_setup.sh`
2. Input	Token is read by `read -s` (hidden prompt, no shell history, never enters chat)	`tools/overleaf_setup.sh`
3. Storage	Token goes straight into OS keychain via `git credential approve` ; remote URL is stripped to a token-free form	`tools/overleaf_setup.sh`
4. Commits	`paper-overleaf/.git/hooks/pre-commit` greps staged content for `olp_[A-Za-z0-9]{20,}` and aborts	auto-installed by setup script
5. Audit	`overleaf_audit.sh` scans working tree, remote URLs, git history, credential files	`tools/overleaf_audit.sh`

Behavioral rules (still apply, but secondary):

Never ask the user to paste a token into chat. If they do anyway: (a) acknowledge it, (b) tell them to revoke it at https://www.overleaf.com/user/settings, (c) recover via keychain if already primed.
Never write a token to a file (
```
.env
```
,
```
.netrc
```
,
```
tools/*.sh
```
, etc.) committed to any repo.
Never include a token in a
```
git remote -v
```
URL — strip it after clone.
On
```
401 Unauthorized
```
from push/pull, tell the user the keychain entry expired and to re-run
```
overleaf_setup.sh
```
. Do not ask for a fresh token.

仅靠行为规则是不够的——后续读取此技能的Agent可能会忘记这些规则。因此，该技能依赖技术防护措施，即使Agent行为异常也能生效：

层级	防护措施	执行位置
1. 设置	`overleaf_setup.sh` 拒绝在非交互式TTY环境下运行（Agent无此环境）	`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` 会检查暂存内容中是否包含 `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中包含令牌——克隆后立即剥离。
若推送/拉取时出现
```
401 Unauthorized
```
，告知用户钥匙串条目已过期，需重新运行
```
overleaf_setup.sh
```
。不要请求新令牌。

Mutual-Exclusion Rule

互斥规则

The single biggest source of pain in two-way sync is simultaneous editing on both sides.

If the user is in an active Overleaf editing session, ARIS skills should read-only access
```
paper/
```
until the user runs
```
/overleaf-sync pull
```
.
If ARIS is in the middle of
```
/auto-paper-improvement-loop
```
or
```
/paper-write
```
, the user should pause Overleaf editing until the loop finishes and
```
/overleaf-sync push
```
is run.

When in doubt, run

status

first.

双向同步中最大的问题来源是双方同时编辑。

如果用户处于活跃的Overleaf编辑会话中，ARIS技能应对
```
paper/
```
保持只读访问，直到用户运行
```
/overleaf-sync pull
```
。
如果ARIS正在运行
```
/auto-paper-improvement-loop
```
或
```
/paper-write
```
，用户应暂停Overleaf编辑，直到循环完成并运行
```
/overleaf-sync push
```
。

如有疑问，先运行

status

。

Output Contract

输出约定

```
paper-overleaf/
```
directory at repo root, git clone of Overleaf project (origin URL has NO token)
```
paper/
```
directory unchanged in role — still the ARIS working copy
Each
```
pull
```
/
```
push
```
operation: a one-line summary back to the user (commits pulled / pushed, file count, link to Overleaf project URL)

仓库根目录下的
```
paper-overleaf/
```
目录，为Overleaf项目的Git克隆版本（远程URL不含令牌）
```
paper/
```
目录的角色保持不变——仍是ARIS工作副本
每次
```
pull
```
/
```
push
```
操作：向用户返回一行摘要（拉取/推送的提交数、文件数、Overleaf项目URL链接）

另请参阅

```
/paper-claim-audit
```
— re-run after pulling Overleaf changes that touch numbers
```
/citation-audit
```
— re-run after pulling Overleaf changes that add/edit
```
\cite{...}
```
```
/paper-compile
```
— local LaTeX build; Overleaf compiles independently in the cloud
Overleaf Git bridge docs: https://www.overleaf.com/learn/how-to/Using_Git_and_GitHub

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

overleaf-sync

Original

Translation

Overleaf Sync

Overleaf 同步

When to Use This Skill

何时使用此技能

Constants

常量

Architecture

架构

Sub-commands

子命令

setup <project-id> — one-time

setup <project-id> — 一次性操作

pull — before each editing session

pull — 每次编辑会话前

Show what changed since last pull

显示自上次拉取以来的更改

Sync only the files the user approved into local paper/

仅将用户批准的文件同步到本地paper/

(or use Edit tool for surgical changes that skip half-sentences)

（或使用编辑工具进行精准更改，跳过未完成的句子）

push — after local editing

push — 本地编辑完成后

1. Always pull first to surface remote drift

1. 始终先拉取以发现远程变更

2. If pull was a no-op, sync local paper → paper-overleaf

2. 如果拉取无变更，将本地paper同步到paper-overleaf

3. Show what would be pushed

3. 显示即将推送的内容

4. Commit + push

4. 提交并推送

status — diagnostic

status — 诊断

Conflict Resolution

冲突解决

Token Security — Defense in Depth

令牌安全——深度防御

Mutual-Exclusion Rule

互斥规则

Output Contract

输出约定

See Also

另请参阅

`setup <project-id>`
— one-time

`setup <project-id>`
— 一次性操作

`pull`
— before each editing session

`pull`
— 每次编辑会话前

`push`
— after local editing

`push`
— 本地编辑完成后

`status`
— diagnostic

`status`
— 诊断