前言¶
多个 AI 编码智能体协作时，经常会遇到这样的问题：Agent A 和 Agent B 同时修改同一文件，谁都不知道对方在改；某个检查点被另一个 Agent 覆盖，导致后续恢复时基于过时假设继续推进；硬性约束写在 Prompt 里，但智能体仍会违反。这些问题最终会变成难以解决的合并冲突。
SyncPoint 是一套面向 AI 智能体协作的协调协议，让多个智能体在同一代码库中更有序地分工、协同和推进工作。
是什么¶
syncpoint-ai-skill 是 SyncPoint 协议在 Claude Code 中的技能实现，为 Claude 提供一套可直接调用的协调能力，包括项目初始化、资源占用、同步门控、任务交接、阶段审查与文件保护。
该技能由社区开发者 @user_88d335e9 发布，分类为 ai-agent，在 SkillHub 上的评分约为 100000，下载次数约 662。
核心功能¶
- 项目初始化：自动初始化 SyncPoint，注册智能体，启动协调服务器，生成编辑器配置。
- 资源占用：在编辑文件前声明所有权，检查冲突，避免多个智能体同时修改同一资源。
- 同步门控：通过硬协议门控，在智能体继续之前验证其路径是否安全，必要时阻塞执行。
- 任务交接：创建检查点，将任务状态完整传递给下一个智能体，包含资源所有权、约束、门控与阻塞信息。
- 阶段审查：发起审查请求，添加检查清单，提交证据，批准或要求修改。
- 文件保护：基于知识库添加硬约束，防止智能体访问受保护资源。
安装与启用¶
该技能以 Claude Code 插件形式提供，安装一次后即可使用。安装完成后，Claude 会自动拥有上述协调能力。
从 SyncPoint 仓库检出代码后，执行以下命令安装插件目录：
claude plugin install ./packages/syncpoint-ai-skill
安装完成后，Claude 会加载该技能，并可以在对话中直接调用相关指令（如 setup、claim、sync、handoff、review、guard 等）。
典型用法¶
- 初始化与配置
在项目根目录执行初始化命令，创建 SyncPoint 配置，注册智能体，并启动协调服务器：
syncpoint setup --agents 2
这会创建 .syncpoint/ 目录，生成智能体清单，并打印可直接粘贴的 MCP 配置块。
- 声明智能体
在 .syncpoint/agents/ 目录下创建清单文件即可声明智能体：
# .syncpoint/agents/architect.yml
version: 1
name: architect
provider: claude-code
role: manager
- 资源占用与冲突检测
在编辑文件前声明所有权，并检查冲突：
syncpoint claim src/config.ts --agent architect --mode exclusive
若有冲突，SyncPoint 会显示谁持有锁以及原因。使用 syncpoint status 查看所有声明、门控与阻塞信息。
- 任务交接与恢复
保存中途进度：
syncpoint checkpoint --agent architect --task <taskId> --summary "Auth module halfway done"
另一智能体恢复任务时会收到完整上下文，包括变更的资源与活跃的阻塞项。
- 硬约束保护
添加受保护资源的约束：
syncpoint knowledge add \
--content "Auth module under audit — do not modify" \
--kind hard_constraint \
--applies-to '{"files":["src/auth/**"]}' \
--severity blocking
后续尝试修改该目录下的文件会被协议级阻塞。
适用场景与注意¶
- 适合需要多个 AI 智能体协同编辑同一代码库的场景，如前后端分工、架构与实现并行、代码审查与重构。
- 需要避免智能体基于过时检查点继续工作的场景，如长期项目、多人协作。
- 注意：该技能通过协议门控与约束保护，但不能替代人工审查与代码审查流程。对于未通过 SyncPoint 控制路径的写入（如直接 shell、git 或编辑器操作），需在后续审查中检查。
短结尾¶
syncpoint-ai-skill 让 Claude 知晓并执行 SyncPoint 协议，从而在多个智能体协作时减少冲突、提高安全性与可控性。相关仓库：https://github.com/MIK-HEAL/SyncPoint
