简体中文 · English
你有没有经历过这种循环： > 换了个 AI。它眨眨眼：这个项目做到哪了？ > > 你深吸一口气，又从盘古开天开始讲。 Baton 就是给 AI 项目准备的接力棒。它把任务、进度、设计规范、踩过的坑和交接记录放进项目，再通过 Git 带到下一台电脑、下一个 AI。 支持 **Codex、Cursor、Claude Code、DeepSeek Harness**。 ## 先用 20 秒搞懂：到底在哪里输入？ 这个表请先看一眼。真的能少绕半小时。 | 你要输入的东西 | 输入到哪里 | 它在干什么 | |---|---|---| |git clone ... | **PowerShell / 终端** | 把 Baton 下载到电脑 |
| baton-install.ps1 | **PowerShell / 终端** | 让 AI 认识 Baton |
| Baton init | **AI 聊天框** | 给你当前打开的项目建立记忆 |
| 上班啦 | **AI 聊天框** | 开始读取进度并继续工作 |
一句话版：
> **终端负责安装，聊天框负责使用。**Baton init 不是 Git 命令，别把它塞进 PowerShell，它会一脸无辜地看着你。
## 🛝 新手三步上车
这是推荐路线。第一次用，先只看这一节。
开始前确认电脑里有：
- [Git](https://git-scm.com/downloads)
- [Node.js 18+](https://nodejs.org/)
- Windows：系统自带 PowerShell 5.1 就能用
- macOS / Linux：需要 [PowerShell 7](https://learn.microsoft.com/powershell/scripting/install/installing-powershell)，然后在 pwsh 里运行命令
### 第 1 步：安装 Baton（在终端里）
#### 如果你用 Codex、Cursor 或 Claude Code
打开 **PowerShell**，依次复制下面两行：
~~~powershell
git clone https://github.com/kakadeka/Baton.git "$HOME/Baton"
& "$HOME/Baton/scripts/baton-install.ps1" -Scope User
~~~
就两行。第一行下载，第二行安装。没有隐藏剧情。
这条命令会一次装好 Codex、Cursor、Claude Code 三端的用户级 Skill，所以不用重复跑三遍。
如果你以前已经下载过 $HOME/Baton，不要再 clone。改用：
~~~powershell
git -C "$HOME/Baton" pull --ff-only
& "$HOME/Baton/scripts/baton-install.ps1" -Scope User
~~~
安装完后，**重新打开 AI，或者新建一个会话**。Skill 通常在新会话启动时加载。
#### 如果你用 DeepSeek Harness
在终端里运行：
~~~powershell
npm install -g @deepseek-ai/dsh@latest
dsh plugin --profile web add @kakadeka/dsh-baton
~~~
然后重启 DSH 的 web profile。你用的不是 web？把它换成自己的 profile 名就行。
### 第 2 步：初始化你的项目（在 AI 聊天框里）
用 Codex、Cursor、Claude Code 或 DSH **打开你真正要开发的项目文件夹**。
然后在 **AI 聊天框** 发这句话：
~~~text
Baton init
~~~
注意，是发给 AI，不是发给 PowerShell。
AI 会为当前项目准备 docs/ai_memory/、.baton/config.json 和对应宿主入口。它不会覆盖你已有的项目文档；遇到冲突会停下来说明。
看到项目里出现 docs/ai_memory/，这一步就算成功。
### 第 3 步：开工（还是在 AI 聊天框里）
新建一个 AI 会话，然后说：
~~~text
上班啦
~~~
如果一切正常，AI 会检查 Git、读取最近进度和交接记录，再给你任务表。
恭喜，你已经用完安装教程了。下面都是“想多了解一点再看”的内容。
## 这三步分别做了什么？
~~~text
第 1 步：安装 Baton 到这台电脑
↓
第 2 步：给当前项目建立接力记忆
↓
第 3 步：让 AI 读取记忆，开始工作
~~~
- **用户级安装**：一台电脑通常只做一次。作用是让 AI 认识 Baton 口令。
- **项目初始化**：每个需要接力的项目做一次。作用是把记忆骨架放进项目。
- **以后工作**：不用再安装。直接说“上班啦”“继续工作”“下班啦”。
只做第 1 步，AI 虽然认识 Baton，但项目还没有自己的长期记忆。Baton init 后，还会得到 AGENTS.md 和 .agents/skills/baton/ 等项目入口。
### Cursor
第 1 步的用户级安装会写入：
~~~text
~/.cursor/skills/baton/SKILL.md
~/.cursor/skills/baton-lean-review/SKILL.md
~/.cursor/skills/baton-debt/SKILL.md
~/.cursor/skills/baton-doctor/SKILL.md
~/.cursor/skills/baton/version.json
~~~
项目执行 Baton init 后，还会得到 .cursorrules、.cursor/rules/baton.mdc 和 .cursor/skills/baton/。
### Claude Code
第 1 步的用户级安装会写入：
~~~text
~/.claude/skills/baton/SKILL.md
~/.claude/skills/baton-lean-review/SKILL.md
~/.claude/skills/baton-debt/SKILL.md
~/.claude/skills/baton-doctor/SKILL.md
~/.claude/skills/baton/version.json
~~~
项目执行 Baton init 后，还会得到 CLAUDE.md 和 .claude/skills/baton/。
### DeepSeek Harness
DSH 的第 1 步叫 **profile 级插件安装**：
~~~powershell
dsh plugin --profile web add @kakadeka/dsh-baton
~~~
它会给这个 profile 安装 19 个原生 baton_* 工具。第 2 步仍然要在目标项目的 AI 聊天框说：
~~~text
Baton init
~~~
profile 插件属于这台电脑，不会跟着项目 Git 跑到另一台电脑；项目记忆会。
## 手动项目级安装（备用路线）
绝大多数新手不需要这一节。只有下面两种情况再用：
- AI 没有识别 Baton init
- 你明确想从终端初始化项目
先进入你的项目，再运行安装脚本：
~~~powershell
cd C:\你的项目路径
& "$HOME/Baton/scripts/baton-install.ps1" -Scope Project -ProjectRoot (Get-Location).Path
~~~
这和在聊天框说 Baton init 的目标相同：给**当前项目**创建记忆和四端适配器。两种方式选一种即可，不需要叠加施法。
如果 $HOME/Baton 还不存在，请先完成新手教程第 1 步。
## 第一次提交前，先看一眼 Git
Baton 靠 Git 把项目记忆带到下一台电脑。已有 Git 仓库不需要重复初始化。
如果这是一个全新项目，可以在终端运行：
~~~powershell
git init
git status
~~~
先用 git status 看清楚哪些文件会被提交，再决定什么时候 git add 和 git commit。不建议闭眼 git add -A，毕竟惊喜应该留给生日，不该留给 Git。
## 常用口令
这些都发到 **AI 聊天框**，不是终端。
| 你说 | Baton 会做什么 |
|---|---|
| 上班啦 | 检查 Git、读取交接和任务，给出任务表 |
| 继续工作 | 从上次唯一下一步继续，不从头考古 |
| 完成 | 把任务转为待验收；你确认后才算已完成 |
| 更新项目文档 | 保存当前进度和交接，不做全天收尾 |
| 这个坑记下来 | 把已验证的坑写进长期记忆 |
| 这个决策记下来 | 保存技术决策和取舍 |
| 下班啦 | 验证、记录、提交、推送，并核对远端 SHA |
| 检查更新 | 只读检查 Baton 是否有新版 |
| 更新 Baton | 经确认后更新，并核对是否真的生效 |
| 修复 Baton | 更新官方 Baton，并重装当前项目镜像、迁移骨架、执行 init/Doctor 后验；不修改业务代码 |
英文环境可以使用 clock in、continue work、complete task、clock out 等对应口令。
## 换电脑或换 AI
### 换 AI，不换项目
直接用另一个 AI 打开同一个项目，然后说：
~~~text
继续工作
~~~
Codex、Cursor、Claude Code 会读取项目里的 Skill 和 docs/ai_memory/。DSH 还要求当前电脑的对应 profile 已安装插件。
### 换电脑
1. 在新电脑安装 Git 和你要用的 AI。
2. git clone **你自己的项目**。
3. 用 AI 打开项目，先说“更新 Baton”，再说“上班啦”。
这里 clone 的是你的项目，不是 Baton 安装仓库。.baton/version.json。没有 PowerShell 也没关系：它会用 Node 把官方 npm 包放到 ~/.baton/runtime，不会把 Baton 源码写进你的项目。若当前 npm 包还不会 --restore-anchor，口令必须停下来报告，而不是假装更新成功。.baton/ 不是整个目录都忽略。config.json 和 manifest.json 应进入 Git；version.json、local/ 和私有扫描清单不进入 Git。
## 四个宿主并不是完全一样
| 能力 | Codex / Cursor / Claude Code | DeepSeek Harness |
|---|---|---|
| 项目记忆、任务、交接 | Skill + Markdown/JSON | 同一套项目文件 |
| Git 操作 | AI 按 Skill 调用宿主命令 | 原生工具编排 |
| baton_* 原生工具 | 没有，按 Skill 做等价流程 | 有，当前组合包提供 19 个 |
| 单写入者保护 | 文件/Git 级规则，不能冒充原子锁 | 插件可提供更强机械门禁 |
| 实际模型与授权证据 | 宿主不提供时如实记 unknown | 可使用 DSH 宿主事件与授权服务 |
共同点是项目记忆和工作流程；不同点是自动化和机械保证。Baton 不会假装四个平台底层能力一模一样。
## 更新与卸载
### 更新
最省心：在 AI 聊天框说 检查更新。确认有新版后再说 更新 Baton。
如果某个业务项目遇到已由 Baton 官方修复的 Bug，直接在该项目聊天框说 修复 Baton。Baton 会更新官方来源，重装用户级和当前项目级 Skill，必要时做不删除历史的迁移，然后执行 Baton init 与 Doctor 后验。业务项目不应复制、修改或维护 Baton 源码；如果官方还没有包含修复的新版本，正确结果是等待发布，而不是现场打补丁。
想自己更新也可以在终端运行：
~~~powershell
git -C "$HOME/Baton" pull --ff-only
& "$HOME/Baton/scripts/baton-install.ps1" -Scope User
~~~
更新后新建 AI 会话；DSH 更新插件后重启对应 profile。只有全局 Skill、项目 Skill 镜像、项目版本锚、报告脚本路径和 init/Doctor 都对齐，才算更新完成。
### 项目级安全卸载
先演练，不写文件：
~~~powershell
& "$HOME/Baton/scripts/baton-uninstall.ps1" -ProjectRoot "C:\你的项目路径" -DryRun
~~~
确认输出后去掉 -DryRun。默认保留 docs/ai_memory/ 与 .baton/config.json；只有显式加 -RemoveMemory 才会删除项目记忆。
当前卸载脚本只处理项目级文件，不会删除用户级 Skill。删除用户级安装时，只删除下面三个根目录里的 baton、baton-lean-review、baton-debt、baton-doctor 子目录，别把整个 skills 文件夹一锅端：
- ~/.agents/skills/
- ~/.cursor/skills/
- ~/.claude/skills/
DSH profile 卸载：
~~~powershell
dsh plugin --profile web remove @kakadeka/dsh-baton
~~~
## 卡住了？先看这里
### git clone 说 $HOME/Baton 已存在
说明以前下载过。不要重复 clone，运行更新命令：
~~~powershell
git -C "$HOME/Baton" pull --ff-only
~~~
如果它不是 Git 仓库，先确认里面有没有重要文件，再手动改名。Baton 不会替你覆盖它。
### baton-install.ps1 不存在
通常是第 1 步的 git clone 没成功。先看终端上方的 Git 报错，不要直接跳到第二行。
### macOS / Linux 提示 pwsh 不存在
先安装 PowerShell 7，再进入 pwsh 执行教程里的 PowerShell 命令。
### 安装成功，但 Baton init 没反应
1. 新建 AI 会话或重启 DSH profile。
2. 检查对应的用户级 SKILL.md 是否存在。
3. 确认 AI 打开的是你的项目目录，不是 $HOME/Baton 安装目录。
4. 明确告诉 AI：“请按 Baton skill 执行 Baton init。”
### git pull --ff-only 说无法快进
Baton 会停下来，不会偷偷 rebase、reset 或覆盖修改。先运行：
~~~powershell
git -C "$HOME/Baton" status
~~~
看清楚差异后再决定，不要为了更新安装器直接 reset --hard。
### “下班啦”但没有 push 成功
只有 git push 成功，而且远端 SHA 等于本地 HEAD，Baton 才应该报告“下班完成”。网络、权限或分支保护失败时，正确答案就是“还没完成”，不许演。
## 安全底线
- 不 force push，不 reset --hard，不危险 clean，不偷偷 rebase。
- 同步默认只允许 ff-only；遇到分叉先停。
- API Key、Token、密码和私钥不写进 Git、项目记忆、报表或交接。
- 历史只追加，或者明确标记“已取代”。
- 公开仓库只包含 Baton 运行所需文件，不包含你项目里的 docs/ai_memory/。
## 仓库与许可证
- GitHub：