内容
# 克劳德叶
将克劳德（以及任何代理）带入Overleaf。克劳德叶是一个可靠的TypeScript桥，它实时驱动Overleaf网页编辑器——列出您的项目、打开文档、读取文档、插入/更改/删除文本——就像一个人正在打字一样，以便协作者实时看到编辑内容。它作为SDK、CLI和克劳德代码的MCP服务器提供。单个登录实例可以跨所有项目工作。
## 功能
- **实时编辑，非git**。编辑通过Overleaf的实时协作通道（ShareJS over Socket.IO）进行，因此它们立即出现在项目中的每个人眼前，归因于您的用户。
- **所有项目，一个实例**。列出您可以访问的所有项目，并通过ID或名称编辑任何项目——无需预先配置项目。
- **完全文档控制**——列出文档、读取文本、在指定位置或行/列插入、替换范围或字面文本、删除范围或行、替换整个文档、创建/删除/重命名文件。
- **编译和错误日志**——触发LaTeX重新编译，并获取状态以及解析的错误和警告（带有文件和行），或完整的原始日志。
- **可靠的设计**——自动重新连接文档、按文档编辑序列化、服务器确认编辑（无静默丢失）。
- **零配置，轻松登录**。无需存储凭证和配置：运行`claudeleaf login`一次，在打开的浏览器中手动登录（处理reCAPTCHA / SSO / 2FA），会话被缓存。
- **三种使用方式**——TypeScript SDK、CLI和MCP服务器，以便克劳德代码可以自主地处理您的项目。
- **自托管友好**——通过一个环境变量指向任何Overleaf实例。
## 入门指南
您不需要克隆或安装任何东西——只需要[Node.js](https://nodejs.org/) 20+（它提供`npx`）。登录一次，然后运行任何命令：
```bash
npx claudeleaf login # 打开您的浏览器；手动登录（处理reCAPTCHA/SSO/2FA）
npx claudeleaf doctor # 检查会话并列出您的项目
```
`login`驱动您已安装的**谷歌浏览器**（或微软Edge）；不需要下载浏览器。会话缓存在`~/.claudeleaf`下，因此每个后续命令都会重用它。
> **推荐：作为专用机器人账户登录**。每个编辑都归因于登录的人，因此为代理创建单独的Overleaf账户，将其邀请到您的项目中作为协作者（**共享 → 可以编辑**），并作为该账户运行`claudeleaf login`。然后，机器人的每次更改都会在Overleaf的历史记录中显示在机器人的名下——透明、易于审查或恢复，并与您自己的编辑明显不同。
> 提示：`npx claudeleaf@latest …`始终获取最新版本。要避免每次运行都获取，请使用`npm install -g claudeleaf`一次性安装，然后直接运行`claudeleaf …`。
### 使用CLI
每个文档命令都需要一个项目（ID或名称），后跟文档路径：
```bash
npx claudeleaf projects # 列出所有项目
npx claudeleaf ls "我的论文" # 列出文档
npx claudeleaf cat "我的论文" main.tex # 打印文档
npx claudeleaf append "我的论文" main.tex "\\section{新}"
npx claudeleaf replace "我的论文" main.tex "foo" "bar"
npx claudeleaf search "我的论文" main.tex "\\section"
npx claudeleaf compile "我的论文" # 重新编译；打印错误/警告
npx claudeleaf compile "我的论文" --warnings --log # 还显示警告 + 原始日志
```
### 与克劳德代码（MCP）一起使用
注册MCP服务器（无需克隆），然后要求克劳德处理您的任何项目：
```bash
claude mcp add claudeleaf -- npx -y claudeleaf mcp
```
这些工具重用来自`claudeleaf login`的会话（它们不会弹出浏览器）。克劳德可以`overleaf_list_projects`，然后读取、编辑和编译任何项目中的文档，ID或名称。
### 使用SDK
```bash
npm install claudeleaf
```
```ts
import { OverleafClient } from "claudeleaf";
const client = new OverleafClient(); // 账户范围；使用缓存的会话
for (const p of await client.listProjects()) {
console.log(p.id, p.name);
}
await client.append("我的论文", "main.tex", "\n% 由代理添加\n");
await client.replaceText("我的论文", "main.tex", "您的论文", "我们的论文");
const compile = await client.compile("我的论文");
console.log(compile.status, compile.errors); // 错误携带 { message, file, line }
```
### 本地开发
```bash
git clone <此仓库> && cd claudeleaf
npm install
npm run claudeleaf -- login # 通过tsx从源代码运行CLI
npm test # 单元测试（无会话时自动跳过实时测试）
npm run build # 编译到dist/
```
## 注意事项
- 克劳德叶编辑实时文档。使用Overleaf的历史记录审查或恢复更改。
- 缓存的会话是一种凭证；它位于`~/.claudeleaf`下，具有限制性权限。
