kakadeka/Baton

Baton — 把项目交给下一个 AI，不必从头解释

Baton 是给 Codex、Cursor 和 Claude Code 使用的项目记忆与交接工具。它把任务、进度、重要决定、踩过的坑和 Git 状态保存在项目里，让你换 AI、换会话或换电脑后，仍能从上次停下的位置继续。

如果你不会写代码，但会让 AI 帮你做一个长期项目，Baton 最适合你：少重复背景，少漏掉未完成事项，也更容易知道代码是否真的提交并推送了。

Baton 不是 AI，不是云盘或云服务，也不是后台常驻程序。它是一组给 AI 阅读和执行的项目规则、模板与脚本；只有你向 AI 发出口令时，它才工作。

你可能正需要它

- 换 AI：昨天用 Cursor，今天想让 Codex 或 Claude Code 接着做，不想再讲一遍需求。
- 换电脑：办公室电脑做到一半，回家拉取项目后，希望进度和注意事项一起回来。
- 开新会话：聊天太长或上下文丢失，新会话仍能读到当前任务和上次交接。
- 长期项目：一个项目做几周或几个月，决定、规范和待办不会只留在聊天记录里。
- 怕 Git 漏操作：说“下班啦”后，Baton 会要求检查提交、推送，并核验远端版本。
- 不想重复踩坑：已经确认的坑和长期决定可以写入项目记忆，后来的 AI 先读再动手。

它不能保证 AI 永不犯错，也不会代替 GitHub 保存代码；它做的是让项目事实有固定位置，并要求 AI 用真实文件和 Git 结果来核对。

安装前先看懂两个层级

| 层级 | 安装几次 | 安装到哪里 | 作用 |
|---|---:|---|---|
| 用户级 | 每台电脑一次 | 当前用户的 Codex、Cursor、Claude Code Skill 目录 | 让三种 AI 都认识 Baton init、上班啦 等口令 |
| 项目级 | 每个项目一次 | 你的项目目录 | 建立可随 Git 同步的项目记忆、交接和三端入口 |

推荐组合：先装用户级，再为每个长期项目执行一次 Baton init。

用户级安装脚本会一次准备好 Codex、Cursor 和 Claude Code，三端没有三套不同的安装命令。项目级内容属于具体项目；只装用户级，不会自动为所有旧项目创建记忆文件。

首次安装可以用一份 Baton clone 启动安装器。此后，标准“更新 Baton”会运行已经安装的 baton-public-update.mjs 引导器：它从 https://github.com/kakadeka/Baton.git 选择最新稳定标签，在临时目录完成校验，再刷新用户级和当前项目，不需要本地 Baton 源码目录，也不依赖 npm。私有的 $HOME\.baton\source.json 只在你明确说“更新本地 Baton 开发版”时使用，绝不会成为标准更新的自动回退。

Windows 零基础安装教程

下面的命令都输入到 PowerShell，不是 AI 聊天框。你可以按 Windows 键，搜索并打开“PowerShell”。每次粘贴一段，按 Enter，等它运行完再继续。

第 1 步：准备 Git、Node.js 和 PowerShell

在 PowerShell 中依次运行：

git --version
node --version
$PSVersionTable.PSVersion

你应该看到 Git 版本、Node.js 版本和 PowerShell 版本。Baton 需要 Node.js 18 或更高版本；Windows 自带的 Windows PowerShell 5.1 可以使用。

如果提示“无法识别”或“不是命令”，先安装缺少的软件，再重新打开 PowerShell：

- Git：
- Node.js：（选择 LTS 版本）
- PowerShell：

第 2 步：把 Baton 放到这台电脑

先检查默认目录是否已经存在：

Test-Path "$HOME\Baton"

- 如果显示 False，这是首次安装，运行：

git clone https://github.com/kakadeka/Baton.git "$HOME\Baton"

- 如果显示 True，说明目录已经存在，不要再次 clone。更新现有 Baton：

git -C "$HOME\Baton" pull --ff-only

如果已有目录不是从这个仓库下载的，或更新命令报错，不要删除目录。把完整错误交给 AI，并说：修复 Baton。

第 3 步：一次安装到三种 AI

仍在 PowerShell 中运行这一个共同安装命令：

& "$HOME\Baton\scripts\baton-install.ps1"

看到“用户级安装完成”，并列出 Codex、Cursor、Claude Code 的安装位置，就表示这一步成功。

安装完成后，完全关闭并重新打开你要使用的 AI，或至少新建一个会话。旧会话可能还不知道刚安装的 Skill。

第 4 步：用 AI 打开你的项目

三种 AI 的安装结果相同，但打开项目和输入口令的位置略有不同：

| AI | 怎样打开项目 | 口令输入在哪里 | 成功标志 |
|---|---|---|---|
| Codex | 在 Codex 中打开或选择项目文件夹 | Codex 聊天框 | AI 识别 Baton init，并开始检查项目和执行项目级安装 |
| Cursor | 选择 File → Open Folder，打开项目根目录 | Cursor 的 AI Chat | AI 识别 Baton init，项目中出现 Baton 入口和记忆目录 |
| Claude Code | 在终端进入项目目录，再启动 Claude Code | Claude Code 对话输入框 | AI 识别 Baton init，并报告项目级初始化结果 |

“项目根目录”就是放着项目源码、通常也有 .git 文件夹的最外层目录。不要只打开其中某个子文件夹。

Codex

1. 打开 Codex。
2. 选择你真正要维护的项目文件夹。
3. 在聊天框发送：Baton init。
4. 等 AI 完成检查；不要把 Baton init 输入 PowerShell。

Cursor

1. 打开 Cursor。
2. 点击 File → Open Folder，选择项目根目录。
3. 打开 Cursor AI Chat。
4. 发送：Baton init。

Claude Code

1. 打开 PowerShell，进入你的项目目录。例如项目在 C:\Projects\MyApp：

Set-Location "C:\Projects\MyApp"

2. 按你平时的方式启动 Claude Code。
3. 在 Claude Code 的对话输入框发送：Baton init。

第 5 步：初始化这个项目

无论使用哪种 AI，都在它的聊天框发送：

Baton init

AI 会调用项目级安装，补齐 Baton 骨架，但不会覆盖已经存在的项目文档。完整初始化要求项目已经是 Git 仓库、有至少一次提交，并配置了名为 origin 的远端仓库。

成功时，你应看到 AI 报告“项目级安装完成”或同等明确结果，且项目根目录出现：

- docs/ai_memory/
- .baton/config.json 和 .baton/manifest.json
- .baton/runtime/baton-closeout.mjs（受管收尾运行时）
- .baton/runtime/baton-public-update.mjs（受管公开更新引导器）
- .agents/skills/baton/、.claude/skills/baton/、.cursor/skills/baton/
- AGENTS.md、CLAUDE.md、.cursorrules
- .cursor/rules/baton.mdc

如果提示没有 Git、没有可读 HEAD 或没有 origin，脚手架可能已经安全写入，但初始化还不算完整。把完整提示交给当前 AI，让它先解释缺什么；涉及新建或连接 GitHub 仓库时，由你确认仓库和可见性后再操作。

第 6 步：第一次上班

继续在同一个 AI 聊天框发送：

上班啦

正常情况下，AI 会同步 Git、核对有没有别人正在写入、读取当前进度，然后给出任务表。出现同步失败、分支冲突、来源不明的修改或上一位仍在工作时，Baton 会停在只读状态并说明原因，不会擅自覆盖代码。

做到这里，Baton 就安装并接入项目了。

最常用的口令

这些内容都发到 AI 聊天框：

| 你说 | 适合什么时候说 | Baton 会做什么 |
|---|---|---|
| Baton init | 第一次接入项目或入口缺失 | 补齐项目级记忆、Skill 和入口 |
| 上班啦 | 开始一次工作 | 同步 Git、检查写入权、读取任务并列出下一步 |
| 继续工作 | 会话中断后回来 | 只读当前快照，从已记录的下一步继续 |
| 完成 | 一项任务做完 | 记录验证证据，等待你验收 |
| 保存设计规范 | 页面或交互规则已经确认 | 把规范保存到项目记忆中 |
| 这个坑记下来 | 已经确认一个会反复遇到的问题 | 保存坑点和处理办法 |
| 这个决策记下来 | 一个决定以后必须继续遵守 | 保存决定和依据 |
| 下班啦 | 本次工作结束 | 更新交接、提交、推送，并核验远端 SHA |
| 检查更新 | 想知道 Baton 是否有新版本 | 只检查，不自动升级 |
| 更新 Baton | 明确要更新本机 Baton | 获取公开 GitHub 最新稳定标签，刷新本机和指定项目的安装内容 |
| 修复 Baton | 安装、识别或初始化报错 | 读取真实错误后按安全顺序修复 |

英文 clock in、continue work、clock out 与中文口令等价。

换电脑时怎么接着做

1. 在电脑 A 的 AI 聊天框说“下班啦”。确认 AI 报告已经 commit、push，并核验远端 SHA 与本地一致。
2. 在电脑 B 安装 Git、Node.js 和 PowerShell，并完成一次用户级 Baton 安装。
3. 在电脑 B clone 或 pull 你的业务项目。
4. 用 Codex、Cursor 或 Claude Code 打开项目根目录。
5. 先说“上班啦”。如果 AI 报告项目入口缺失，再说 Baton init。

项目记忆和项目级入口会通过业务项目的 Git 仓库移动；用户级 Skill 属于每台电脑，所以新电脑仍要安装一次。

项目里的文件与隐私

docs/ai_memory/ 会保存任务、交接、决定、规范和坑点；.baton/config.json 与 .baton/manifest.json 用于恢复和核对项目安装。.baton/runtime/baton-closeout.mjs 与 .baton/runtime/baton-public-update.mjs 是随 Git 传递的受管运行时，只含 Baton 收尾和固定公开源更新逻辑，不含项目内容。这些文件通常需要和项目代码一起进入 Git，才能在不同 AI 和电脑之间接力。

.baton/local/ 只属于当前电脑，不应提交。Baton 的模板会为这些本机文件准备忽略规则。

请记住：

- 不要把 API Key、Token、密码或私钥写进聊天交接或项目记忆。
- 如果业务项目含敏感信息，请使用你控制的私有 Git 仓库；Baton 不会改变仓库的公开或私有属性。
- 用户级安装只复制 Baton Skill，不会上传你的项目。
- 安装或初始化 Baton 不会自动修改业务功能代码。

常见问题

git、node 或脚本无法运行

先回到“第 1 步”检查版本。不要只截取最后一行错误；复制从命令开始到错误结束的完整内容，交给 AI，并说：修复 Baton。

Baton init 被当成普通聊天，没有执行

确认你已经运行用户级安装，然后完全重启 AI 或新建会话。还不行时，把当前 AI、项目路径和完整回复交给 AI，并说：修复 Baton。

clone 提示目标目录已经存在

不要反复 clone，也不要直接删除 $HOME\Baton。按照第 2 步的“显示 True”分支更新；若更新失败，把完整错误交给 AI。

初始化提示没有 Git、HEAD 或 origin

这表示项目还不能完成 Git 接力。请让 AI 解释当前项目缺少哪一项，再由你确认是否初始化 Git、创建首次提交或连接远端仓库。不要让 AI 猜远端地址。

安装后 Cursor 能用，另一个 AI 不能用

共同脚本会安装三端 Skill。先完全重启不能识别的 AI；如果仍失败，让 AI 检查对应用户级 Skill 是否存在，并说：修复 Baton。

我只想临时试试，需要项目级安装吗？

用户级安装让 AI 认识 Baton；项目级安装才会把记忆和交接放进具体项目。临时聊天可以不初始化，长期项目建议两者都装。

高级：不用聊天框，直接在终端初始化

只有在你明确知道项目根目录时才使用。下面示例路径真实可运行，但请先把示例目录改成你自己的项目路径：

& "$HOME\Baton\scripts\baton-install.ps1" -Scope Project -ProjectRoot "C:\Projects\MyApp"

从项目引导器执行标准公开更新（先替换项目路径）：

node "C:\Projects\MyApp\.baton\runtime\baton-public-update.mjs" --project "C:\Projects\MyApp"

如果项目引导器缺失，使用用户级副本：

node "$HOME\.baton\runtime\baton-public-update.mjs" --project "C:\Projects\MyApp"

这两条命令都只使用固定公开 GitHub 仓库。维护者只有在明确要安装本地开发 checkout 时才说“更新本地 Baton 开发版”；该独立流程可以读取 $HOME\.baton\source.json，但绝不会作为标准更新的隐式回退。

Baton 不会在后台自动更新；只有你明确说“更新 Baton”或手动运行更新命令时才会变化。

仓库与许可证

- GitHub：
- npm：@kakadeka/baton
- License：Apache-2.0

Pass your project, not your context.