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