Agent Handoff v0.6.0 跨电脑同步：Git、EVENTS.jsonl、CONTEXT.md 使用方法

适用版本与要解决的问题

本文以 Agent Handoff v0.6.0 的跨会话记忆能力为例，说明如何在公司电脑和家里电脑之间共享一个 AI 编程项目的需求、决策、测试结果和下一步任务。

最终效果不是两台电脑实时同步，而是：

Agent Handoff 将项目事实写入 .agent-handoff/；
Git 提交代码和需要共享的记忆文件；
另一台电脑拉取后重建状态，新的 Agent 从 CONTEXT.md 接着工作。

Agent Handoff 不负责同步完整聊天、操作系统环境、依赖、密钥或登录状态。

1. 记忆文件结构

初始化项目：

bash 复制代码

agent-handoff memory init .

生成的核心目录如下：

text 复制代码

.agent-handoff/
├── EVENTS.jsonl   # 唯一事实来源，追加式事件日志
├── STATE.json     # reducer 根据事件归约出的当前状态
└── CONTEXT.md     # 给下一个 Agent 的压缩摘要，最多 200 行

EVENTS.jsonl 每行一个 JSON 事件，记录需求、进度、决策、阻塞、测试和交接。STATE.json 与 CONTEXT.md 都是派生产物，事件日志才是恢复状态时应该优先检查的文件。

2. 记录需求、进度和测试

单条事件适合记录开发过程中的明确事实：

bash 复制代码

agent-handoff memory record . \
  --type task \
  --text "完成用户登录模块" \
  --task-id login \
  --agent company

agent-handoff memory record . \
  --type progress \
  --text "登录接口已完成，等待前端联调" \
  --status in_progress \
  --agent company

agent-handoff memory record . \
  --type test \
  --text "登录模块测试通过" \
  --command "npm test" \
  --tests 12:0 \
  --evidence-level verified \
  --agent company

建议只记录以下事件，不要把所有聊天复制到日志：

需求确认或范围变化；
技术方案和关键取舍；
任务完成、失败、阻塞和解除；
测试命令与结果；
交给下一个 Agent 的下一步。

reported 只代表 Agent 自报；只有 observed 或 verified 证据，才能把任务可靠地视为完成。测试结果最好带命令、通过数和失败数，不要只写"测试过了"。

3. 用 checkpoint 收尾

会话结束时可以从 stdin 一次性写入结构化进度：

bash 复制代码

agent-handoff memory checkpoint . --from-stdin --agent company <<'EOF'
{
  "completed": ["登录接口完成"],
  "inProgress": ["等待前端联调"],
  "blocked": [],
  "decisions": ["继续使用现有 PostgreSQL 用户表"],
  "nextSteps": ["补充登录失败用例并联调页面"],
  "tests": [
    {"command": "npm test", "passed": 12, "failed": 0}
  ]
}
EOF

字段和事件的对应关系：

checkpoint 字段	生成事件	作用
`completed`	`progress.updated`	记录完成项；有完整通过测试时可标记为 verified
`inProgress`	`progress.updated`	记录仍在进行的任务
`blocked`	`blocker.opened`	记录阻塞原因
`decisions`	`decision.recorded`	记录技术取舍
`nextSteps`	`handoff.created`	渲染到上下文的下一步
`tests`	`test.completed`	记录测试命令和计数

收尾后执行：

bash 复制代码

agent-handoff memory verify .
agent-handoff handoff .

verify 会检查文件是否齐全、事件是否可解析、状态是否与日志一致、证据 commit 是否存在、日志是否泄露密钥以及上下文行数。

4. 公司电脑到家里电脑的 Git 流程

公司电脑

bash 复制代码

# 先执行上一节包含 JSON 输入的 checkpoint 命令
agent-handoff memory verify .
git status
git add src/ test/ package.json
git add -f .agent-handoff/EVENTS.jsonl \
  .agent-handoff/STATE.json \
  .agent-handoff/CONTEXT.md
git commit -m "记录登录模块开发进度"
git push

默认情况下 .agent-handoff/ 在 .gitignore 中。这个默认值适合不想共享本地记忆的个人项目，但跨电脑协作时必须显式 git add -f。提交前建议检查：

bash 复制代码

git diff --cached -- .agent-handoff

家里电脑

bash 复制代码

git pull --rebase
agent-handoff memory rebuild .
agent-handoff memory context .
agent-handoff handoff .

rebuild 以事件日志为输入，重新生成 STATE.json 和 CONTEXT.md。context 适合在新会话开始时读取，handoff 适合生成完整交接说明。两台电脑需要各自准备 Node.js、项目依赖、环境变量和 Agent 工具。

5. 接入 Claude Code、Cursor、Codex、OpenCode 和 DeepSeek Harness

Agent Handoff 使用 stdio MCP 服务器向 AI 编程工具提供三个能力：读取项目上下文、追加项目事件、运行状态校验。

先生成配置并审查：

bash 复制代码

agent-handoff memory adapt claude-code
agent-handoff memory adapt cursor
agent-handoff memory adapt codex
agent-handoff memory adapt opencode
agent-handoff memory adapt deepseek-harness

确认路径和参数后再安装：

bash 复制代码

agent-handoff memory adapt opencode --install

跨电脑配置要注意形态差异：

平台	配置特点	跨电脑建议
Claude Code	项目 `.mcp.json` 与 hooks	按项目重新批准信任和 MCP
Cursor	使用 `${workspaceFolder}` 占位符	项目配置通常可提交复用
Codex	TOML 参数可能是绝对路径	每台电脑分别生成或写入全局配置
OpenCode	写入项目 `opencode.json` 的 `mcp`	检查项目路径后重启生效
DeepSeek Harness	写入用户目录的 profile patch	每台电脑单独安装，不当作项目文件同步

平台配置解决"Agent 能否调用记忆工具"，Git 解决"另一台电脑能否拿到记忆文件"，两者是两件事。

6. 并发修改与冲突恢复

最稳妥的顺序是：

text 复制代码

公司：checkpoint -> verify -> commit -> push
家里：pull -> rebuild -> context -> 开始工作

如果两台电脑同时改同一个分支，源代码和 EVENTS.jsonl 都可能冲突。并行开发时使用不同分支；合并事件日志后，确认每一行都是完整 JSON，再重建和校验：

bash 复制代码

git status
agent-handoff memory rebuild .
agent-handoff memory verify .

不要只手改 STATE.json。它是派生状态，手改后下一次 rebuild 仍会被事件日志覆盖。需要纠正历史时，应修正事件日志，再重新生成派生产物。

7. 同步边界与安全

不会自动同步的内容包括：未提交代码、完整聊天记录、API Key、.env、私钥、平台登录态、全局插件、订阅额度、Node.js 和依赖环境、本机绝对路径配置。

记忆层会在写入前进行字段级脱敏，也会清理项目绝对路径；MCP 服务器只使用 stdio，不开放网络端口。但脱敏不是把敏感数据放进摘要的理由。事件只写结论和必要证据，不粘贴生产密码、客户数据和完整终端输出。推送前检查 staged diff，密钥已经泄露时先撤销或轮换，再处理代码和 Git 历史。

8. 结论

Agent Handoff 的跨电脑用法可以概括成一句话：用事件日志保存项目事实，用 Git 搬运项目事实，用 rebuild 在另一台电脑恢复上下文。

它适合解决换电脑、换 Agent、换会话之后的"项目进度断档"，不适合替代网盘、远程开发环境或聊天记录归档。只要把代码提交和记忆 checkpoint 放在同一个收尾动作里，公司电脑和家里电脑就能沿着同一条开发记录继续推进。

下载地址

参考资料：