agentsync (remote)

agentsync-remote

xylem 技术栈的一部分，详见 xylem。

一个 Cloudflare Worker MCP 服务，让手机上的 claude.ai 成为 agentsync 协调网格中的一员——使用相同的 claims.json、相同的 agentsync 分支，以及与本地 agentsync 相同的重叠检测和比较并交换规则，无需 git，也无需本地克隆。

笔记本电脑上的 Claude Code（本地 agentsync）和手机上的 claude.ai（agentsync-remote）会针对同一个共享 claims.json 认领工作。两种传输方式，一个网格。在 claims.json 中，本地节点和远程节点无法区分，除非查看其 Agent ID。

同源项目，而非分支。 这是在与本地 agentsync 相同的协调文件上增加第二种传输方式，而不是它的一个变体。关于 git push 如何通过 GitHub contents API 实现比较并交换，请参阅 DESIGN.md。

它能为你做什么

通过 Streamable HTTP MCP 提供七种工具：

工具	功能
survey	查看整个看板：每个节点的认领、你的冲突以及邮箱。
claim	认领工作；如果与活跃节点的工作重叠，则会阻止（比较并交换安全）。
check_conflicts	重新检查你的认领与其他节点是否冲突，可选指定一个分支。
update_status	将你的认领状态依次设为 planning / in-progress / done。
release	将你的认领标记为已完成（已完成的工作不会阻塞其他节点）。
history	查看协调分支上的近期提交（本地和远程交错显示）。
mailbox	人工参与的备注：在桌面端提问，在手机端回答。

部署你自己的实例（一键部署，无需命令行）

在你自己的 Cloudflare 账户中自托管此 Worker。每个步骤都可以通过点击完成——无需接触终端。

1. 点击部署到 Cloudflare

点击上方按钮。Cloudflare 会：

• 将 agentsync-remote fork 到你的 GitHub 账户，
• 在你的 Cloudflare 账户中创建 Worker，并
• 连接 Workers Builds，这样你 fork 后续的推送就会自动触发重新部署。

无需配置数据库或其他资源——此 Worker 不会自行保存状态（所有内容都存储在你的 GitHub 仓库中），因此只需部署 Worker 本身。

部署对话框中，Cloudflare 会显示 Worker 的变量。请设置：

变量	设置为
REPO	你的协调仓库，格式为 owner/name（agentsync 分支将存放 claims.json 的仓库）。这是唯一必须更改的变量。
AGENT_ID	保留为 jonny-mobile，或为此节点选择一个 ID。
BRANCH	保留为 agentsync，除非你想使用其他协调分支。
CLAIMS_PATH	保留为 claims.json。

完成部署。（如果你在此处跳过设置 REPO，之后可以在控制面板中设置——见下文。）

2. 创建 GitHub 令牌，然后添加两个 Worker 密钥

Worker 会读取两个密钥。它们不属于部署对话框的一部分——首次部署后，请在控制面板中添加一次。

首先，创建 GitHub 令牌（这是 GH_PAT 的值）：

GitHub → Settings → Developer settings → Fine-grained personal access tokens → Generate new token：

• Repository access： Only select repositories → 仅选择你的协调仓库（即你在 REPO 中填写的仓库）。
• Permissions → Repository permissions → Contents： Read and write。
• 不要设置其他权限。生成令牌并复制。

然后，将两个密钥添加到 Worker：

Cloudflare 控制面板 → Workers & Pages → 你的 Worker → Settings → Variables and Secrets → Add → 选择类型 Secret → 逐个添加，然后 Deploy：

密钥	值
AUTH_TOKEN	自行生成的长随机字符串。它用于锁定端点——请像密码一样妥善保管。
GH_PAT	刚刚创建的细粒度 GitHub 令牌。

在此页面上时，请确认 REPO 变量指向你的协调仓库（如果你在部署对话框中跳过了这一步，请在此处设置）。

设置 AUTH_TOKEN 之前，Worker 会对每个请求返回 404（默认拒绝访问）。设置 GH_PAT 之前，工具会返回清晰的错误，指出缺少哪个密钥。这是有意为之——未配置的端点看起来就像不存在一样。

3. 在 claude.ai 中添加连接器

找到 Worker 的 URL：Workers & Pages → 你的 Worker 页面会显示该 URL，格式为 https://<your-worker-name>.<your-subdomain>.workers.dev。

claude.ai（网页）→ Settings → Connectors → Add custom connector。粘贴 Worker URL，并在末尾添加 /mcp/ 和你的 AUTH_TOKEN：

https://<your-worker-name>.<your-subdomain>.workers.dev/mcp/<AUTH_TOKEN>

路径中的令牌就是身份验证方式——没有单独的登录步骤。

4. 测试

向 Claude 发送请求：“call survey”。你应该会看到协调看板（新建的网格中 claims 为空——Worker 会为你初始化分支和文件，因此全新的空仓库无需手动设置）。

🔒 安全——连接器 URL 是凭据

连接器 URL 的路径中包含你的 AUTH_TOKEN （…/mcp/<AUTH_TOKEN>）。**任何拥有该 URL 的人都可以调用你的 Worker，并读取/写入协调文件。**请像对待密码一样妥善保管整个 URL：

• 不要将它粘贴到截图、问题、聊天记录或提交中。
• 任何拥有该 URL 的人都是你网格中的对等方——仅与信任的 Agent/人员分享。
• **轮换令牌会使旧 URL 失效。**如需撤销访问权限，请在 Settings → Variables and Secrets 中更改 AUTH_TOKEN 并重新部署；所有旧的 …/mcp/<old-token> URL 都会立即返回 404。在 claude.ai 中使用新的 URL 更新连接器。

GH_PAT 同样是凭据——将其权限范围限定为仅你的协调仓库，且仅授予 Contents：Read and write，这样即使泄露也无法访问其他内容。

为什么令牌位于 URL 路径中，以及这会带来什么代价

这是有意为之的设计选择，而非疏忽。claude.ai 自定义连接器无法可靠地发送自定义标头，因此无法依赖 Authorization: 标头——这是显而易见的替代方案。将凭据放在路径中，才能让连接器正常工作。

请清楚了解其代价，因为这与使用标头不同：

• URL 会被记录在请求正文永远不会出现的地方。浏览器历史记录、shell 历史记录、代理和 CDN 访问日志、崩溃报告、错误报告、屏幕截图、“复制链接”按钮，以及Agent 会话记录。在生成本节内容的审计过程中，发现这些 Worker 的连接器 URL 在单台机器上的13 份本地会话记录中出现了约 54 次——没有人刻意粘贴；它们只是 Agent 回显的工具配置的一部分。
• **Worker 本身不会记录它。**每条日志都将路由记录为 /mcp/***。泄露面是 Worker 周围的一切，而这些恰恰是你无法审计的部分。
• 令牌一旦泄露，持有者就会成为你网格中的完整对等方——无需第二因素，也没有逐个调用方的身份标识，就能认领、强行覆盖你的认领、释放你的认领，以及向邮箱发送消息。除了令牌之外，没有其他可撤销的内容，也没有日志能告诉你是谁使用了它。

实用建议：

1. 按计划轮换，而不只是怀疑泄露时才轮换——假设 URL 已被记录在某个你无法控制的地方。轮换成本很低：更改 AUTH_TOKEN，然后更新连接器。
2. 如果你分享过配置了该连接器的机器上的终端录屏、会话记录、屏幕截图或错误报告，立即轮换。
3. 使用较长的随机令牌（32 字节以上，例如 openssl rand -hex 32）。比较内容和长度时都采用恒定时间，因此长度不可被观测——但熵仍然是抵御猜测的唯一防线。
4. 如果以后有机会改用标头或 OAuth，就用它。这种权衡是客户端强加的，并非首选。

跨传输方式演练 — 两种传输方式，一个网格

这正是整个方案的核心。笔记本电脑和手机通过一个文件协调。

在 PC 上（本地 agentsync、Claude Code）：

> agentsync claim --task "refactor auth" --touches src/auth --branch feature/auth
{"status": "claimed", ...}          # writes claims["laptop"] on the agentsync branch

在手机上（claude.ai + agentsync-remote）：

You: call survey
Claude: laptop is active — task "refactor auth", touches src/auth, branch feature/auth.

You: claim task "tidy auth helpers", touches src/auth/helpers.ts
Claude: blocked. Overlap with an active peer claim:
        laptop — "refactor auth" — shared_files: ["src/auth/helpers.ts"]
        Narrow `touches`, wait, or re-call with force=true.

You: mailbox "Taking src/auth/helpers.ts once you land the refactor — ok?" to "laptop"
Claude: posted.

回到 PC 上，桌面 Agent（或你）通过 survey / mailbox 读取笔记，回复并释放：

> agentsync mailbox "go for it, helpers are stable now"
> agentsync release --note "refactor landed"
{"status": "released"}              # laptop's claim -> status "done"

⚠️ 已知缺口：目前不同层级之间的邮箱只能写入，无法读取

上面的“回到 PC 上”这一步目前还无法实现。 此 Worker 的 mailbox() 会将顶层 notes[] 数组写入 claims.json，而 本地 Python agentsync 服务不认识 notes —— 它没有提供 mailbox 工具，而且它的 survey() 只会返回 me、branch、partners 和 stale_claims。从手机发出的笔记会正确写入文件，但桌面端的同伴永远看不到。

这比通常的功能缺失影响更大，因为仓库级别的 Agent 指令要求 Agent 通过此邮箱提出需要判断的问题。一个会悄无声息地吞掉问题的备用出口，比没有备用出口更糟：Agent 以为自己已经提问，然后等待，或者在无人能看到问题的情况下继续操作。

在本地端实现该功能之前，请从远程同伴读取邮箱 （调用不带 message 的 mailbox，或使用 survey），或者直接在协调分支上读取 claims.json。

本地端所需的改动（位于 Python agentsync 包中 —— 这是一个单独的仓库，此处有意不作修改）：

1. 解析并保留 notes。 claims 文件读取器必须能完整读写顶层 notes 键。目前，无法识别的键可能会在下一次本地写入时被丢弃，从而删除远程同伴的笔记。保留未知的顶层键是最基本的安全改动，应优先独立完成。
2. 在 survey() 中显示笔记 —— 在 partners/stale_claims 旁添加 notes 字段，默认值为 []。
3. 添加本地 mailbox(message=None, to=None) 工具，与此处的工具保持一致：在本地认领写入已有的同一 compare-and-swap 操作中，将 {from, to, message, at} 追加到数组，并将保留数量限制为最近的 200 条笔记（此 Worker 会在达到上限时优先淘汰最早的笔记 —— 两端必须保持一致，否则会互相争抢文件）。

磁盘上的数据结构在两个方向上已经兼容：此 Worker 只会在 notes 非空时写入该键，因此没有邮箱活动的 claims.json 与纯本地输出的字节结构完全相同。

再次回到手机上：

You: claim task "tidy auth helpers", touches src/auth/helpers.ts
Claude: claimed.                    # laptop is "done" now, so it no longer blocks

You: (later) release note "helpers tidied"
Claude: released.

以上每一步都是针对同一分支上的同一个 claims.json 进行 compare-and-swap。笔记本电脑从未看到远程同伴；手机从未看到 git 仓库。却共用同一个网格。

配置

非机密配置位于 wrangler.toml。每个变量都有默认值，因此无需编辑即可使用 Deploy 按钮；请将 REPO 改为你自己的仓库。

变量	默认值	含义
REPO	jarmstrong158/agentsync-remote	协调仓库的 owner/name。
AGENT_ID	jonny-mobile	此同伴在 claims.json 中的 id。
BRANCH	agentsync	协调分支。
CLAIMS_PATH	claims.json	协调文件。

两个密钥需要在控制面板中设置，绝不能放在仓库中：AUTH_TOKEN（用于锁定端点）和 GH_PAT（对协调仓库拥有 GitHub Contents 读写权限）。

将本地 agentsync 和此 Worker 指向同一个 REPO + BRANCH + CLAIMS_PATH，它们便会共用一个网格。

可靠性

在竞争条件下的协调正确性是经过测量的，而非仅作断言——完整说明见 docs/RELIABILITY.md，可通过以下命令复现。

• 49 / 49 项自动化测试全部通过，涵盖五种不同的 CAS 竞争场景，以及全部三种重叠检测模式（精确 · 目录包含 · glob，且每种模式都测试了两个方向）。
• 1000 次模拟并发竞争（test/stress-cas.test.ts，种子为 0x5eed）：0 次丢失声明，0 次重复授权，并且每次竞争都触发了真实的 409 重试——因此结果并非由简单串行执行虚增。
• 已测试失败关闭式身份验证——错误令牌、未设置 AUTH_TOKEN，以及非 /mcp 路径均返回 404；缺少 GH_PAT 时会显示明确的错误，而非静默失败。
• MCP 握手经过加固——initialize 不会发起网络调用，因此即使在冷启动的隔离环境中也能立即响应；它会协商客户端请求的协议版本，而不是拒绝版本略新的客户端；任何位置发生意外抛错，都会转换为格式正确的 JSON-RPC 错误，而不会返回重连客户端会视为硬性故障的裸 500。
• 结构化日志让故障一目了然——每个请求都会输出一行 JSON（request / auth / handshake / tool_call / error，路径令牌始终经过脱敏），因此在 Cloudflare Workers Logs 中，只需设置一个筛选条件就能找到握手中断或工具调用缓慢的问题（wrangler.toml 中已启用 [observability]）。

如实说明： 千次竞争是在进程内模拟的——GitHub 的 409 比较并交换机制由一个使用 fetch 模拟的伪对象复现（test/helpers.ts），并未通过实际 API 进行测试。结果验证的是 Worker 的协调逻辑——也就是生产环境中运行的部分——而非 GitHub 的 API、网络或现实世界的延迟。

维护者 / 本地开发

规范仓库（jarmstrong158/agentsync-remote）通过 GitHub Actions → Wrangler 部署（.github/workflows/deploy.yml）： 每次推送到 main 都会运行测试套件，只有全部通过才会部署。该工作流仅适用于规范仓库，因此通过 Deploy 按钮创建的 fork 不会尝试运行它——你的 fork 会改由 Workers Builds 重新部署。

本地检查（无需 Cloudflare 凭据）：

npm install
npm test          # vitest, fetch-mocked — no live GitHub calls
npm run typecheck
npx wrangler deploy --dry-run --outdir dist   # bundle check

另请参阅

• agentsync — 本地传输方式（在你的设备上运行的 Claude Code）。同一文件，同一规则；这是配套的传输方式。
• DESIGN.md — CAS 转换、重叠语义，以及 MCP 处理程序为何采用无状态、手工实现的方式。
• docs/RELIABILITY.md — 经测量的可靠性报告：49/49 项测试、五种 CAS 竞争场景，以及 1000 次带种子的竞争测试。
• 部署到 Cloudflare 的按钮 — Cloudflare 关于上文所用一键部署流程的文档。

相关项目

• agentsync — 此传输方式所映射的、本地且以 Git 为核心的原始项目；以及 xylem 技术栈中心。