Task Checkpoint

Task Checkpoint MCP

给长任务做"做一步、存一步"的存档：中断后新会话能接着做，做错了能退回任意一步。

一个 stdio MCP 服务器，只用 Python 标准库，不装任何第三方包。

快速开始 | 工具 | 客户端配置 | 使用限制 | English

快速开始

一、装

pipx install task-checkpoint-mcp

二、在客户端里接上（Claude Code、Codex、Cursor 等都是同一段配置）

{

"mcpServers": { "task-checkpoint": { "command": "tc-mcp", "args": [] } } }

三、把 `SKILL.md` 装进技能目录，不装的话 Agent 不会主动存档

tc-mcp --install-skill ~/.claude/skills/task-checkpoint

SKILL.md 随包一起装（wheel 里的包数据），不需要仓库、也不需要联网。想看内容用 tc-mcp --print-skill，想知道它在哪用 tc-mcp --skill-path。

（技能目录按客户端而定，见下面"把 SKILL.md 装进 Agent 的技能目录"。）

四、交给 Agent 用。 一个任务就四步：

tc_init    开任务

tc_save 每完成一步存一次（带 conclusion 和 next） tc_resume 新会话开头先调这个接上进度 tc_restore 退回去（先 apply:false 预览，再 apply:true）

五、不用记工具名，直接说人话。

用 task-checkpoint 开个任务，目标是把 user 模块拆成 service 和 repository 两层。每完成一步存一次档，带结论和下一步。

它会调 tc_init 建任务，之后每完成一步调一次 tc_save。中途换会话、或者隔天接着做，你说一句"接着上次的做"，它调 tc_resume 就把进度拿回来了。

（"每完成一步就存档"这条约束的可靠来源是 SKILL.md —— 装进技能目录之后它是硬规则；不装，就只能靠你每次提醒。）

中途被打断、隔天换个模型重开，新会话调一次 tc_resume 拿到的是这个：

任务：重构认证模块

目标：把 session 改成 JWT 当前步骤：3 下一步：把三个视图函数切到新入口，删旧函数 未落档：src/views/auth.py, src/views/user.py

handoff 字段就是这段文本，可以直接粘给新会话。它同时告诉你哪几个文件改了但还没落档。

为什么不直接用 git stash 或随手 commit 一下

值得装：多步、可能被中断、需要能退回的编码或文档任务。 不值得装：一次能做完、不需要回退也不需要交接的改动。

装之前先知道

• 需要 Python 3.10 或更新，只用标准库。
• 不碰你的 git 历史：不 commit、不 reset、不 clean、不动已有分支和 HEAD，只额外加 refs/checkpoints/... 引用。
• 不是 git 仓库也能用，功能一样，只是少了那层 git 引用。
• 不保存聊天记录，只保存工作区文件和模型主动声明的步骤说明。
• 存档默认写在工作区的 .checkpoints/；指定外部 store 时，工作区仅留一个不含文件内容的 .task-checkpoint-store.json 路径指针。
• 敏感文件识别是路径黑名单，盖不全。 别把凭据放在被扫路径里 —— 详见"使用限制"。

安装

方式一：装成命令（推荐）

pipx install task-checkpoint-mcp

或

pip install task-checkpoint-mcp

也可以直接从 git 装，跟着仓库走、不走 PyPI 的版本号：

pipx install "git+https://github.com/qddfxp/task-checkpoint-mcp"

装完在客户端里用 tc-mcp 启动。包里有两个等价的入口点：tc-mcp 和 task-checkpoint-mcp（后者是给 uvx 这类按包名找命令的 runner 用的）：

{

"mcpServers": { "task-checkpoint": { "command": "tc-mcp", "args": [] } } }

方式二：直接用源码（不用安装）

git clone https://github.com/qddfxp/task-checkpoint-mcp

{

"mcpServers": { "task-checkpoint": { "command": "/absolute/path/to/python", "args": ["/absolute/path/to/task-checkpoint-mcp/scripts/tc_mcp.py"] } } }

command 要写解释器的绝对路径，不要写 python —— 客户端不一定能解析到你要的那个。装过之后也可以直接 python -m tc_mcp。

方式三：用 npx 启动

npm 上有一个同名的 task-checkpoint-mcp，但它是启动器，不是服务器本体：

npx -y task-checkpoint-mcp

它只做一件事：找到本机装了 tc_mcp 的 Python 解释器，然后把 stdio 透传给 python -m tc_mcp。所以本机仍然要先有 Python 包（方式一或方式二）。没有的话它会打印安装命令、以退出码 1 结束，而不是丢一堆 traceback 给你。

适合客户端只认 npm 式启动命令的情况：

{

"mcpServers": { "task-checkpoint": { "command": "npx", "args": ["-y", "task-checkpoint-mcp"] } } }

npx -y task-checkpoint-mcp --version / --help 是启动器自己的开关，不需要本机有 Python。

配置文件放哪

上面那段 mcpServers JSON 要写进客户端的配置文件。各客户端的位置和顶层键：

两个容易踩的：

VS Code 的顶层键是 `servers`，不是 `mcpServers`。 直接抄上面的 JSON 不会生效，得改键名：

{

"servers": { "task-checkpoint": { "command": "tc-mcp", "args": [] } } }

Codex 用 TOML。 同样一段配置要写成：

[mcp_servers.task-checkpoint]

command = "tc-mcp" args = []

其余客户端以各自的文档为准。

怎么用

最重要的一条：文件变化由后台线程自动记录，但"这一步在做什么、结论是什么、下一步干什么"只有模型主动调 tc_save 才会留下。

所以要让 Agent 每完成一步就存一步 —— 这份约束写在 SKILL.md 里，得把它装进 Agent 的技能目录（见下面"把 SKILL.md 装进 Agent 的技能目录"）。不装它，文件回退点照常产生，但没人知道当初要干什么、下一步该干什么。

四条铁律：

1. 开长任务前先 tc_init，一个任务一个名。已有活动任务会被挂起而不是关闭，可以 tc_switch 切回去。
2. 每完成一步就 tc_save，并且必须填 `conclusion` 和 `next`。不填，新会话就只看得到一堆文件路径。
3. 新会话、或中断后继续时，第一件事是 `tc_resume`，不要从零猜进度。
4. 回退前先预览：先 apply: false 看清单，确认了再 apply: true。

一步的粒度：能独立说清"做完了、结论是 X"的单元。太细（每个文件一次）会淹没有效信息，太粗（整个任务一次）就失去了回退的意义。

工具

10 个。第一个参数都是 root，指工作区目录（通常是当前项目的绝对路径）。

tc_save 的完整参数：

• title（必填）——这一步一句话标题，写"做了什么"，不写"改了什么"
• conclusion——这一步的结论。最有价值的字段
• next——下一步要干什么。接续工作的关键
• description——为什么这么做（决策理由，事后没人记得）
• verified——已验证项列表（跑了什么测试、确认了什么事实）
• open_questions——还没解决、留给后面的问题
• close: true——收尾时用。关闭后不能再存档，但还能读

回退操作本身也会被记成一条变更记录，返回里的 recovered 就是它的 drift_id —— 退错了可以再用它退回来。

返回值里几个值得看的字段

• tc_resume.handoff —— 一段现成的交接文本，可以直接粘给新会话；drift_paths 是工作区里还没落档的改动；health.errors 是存档自身的问题
• tc_save.idempotent —— 同一步（标题、文件摘要、结论、下一步、已验证项都一样）重复存，不会产生重复步骤
• tc_save.active_task_changed —— 传了别人的 task_id 时活动任务会被切过去（原任务变 suspended），这个字段就是在提示这件事
• tc_restore.recovered —— 回退本身也会被记成一条变更记录，这就是它的 drift_id
• tc_restore.plan.unrestorable / skipped_paths —— 目标里没能还原的文件；预览和执行给的是同一份清单
• tc_capture.waiting / partial —— 还在静默期，以及中间那条不完整的记录
• tc_init.exclude —— 回读你这次设进去的排除模式
• tc_export.path —— 交接包目录，里面有一个 HANDOFF.md，是给接手方的提示词

把 SKILL.md 装进 Agent 的技能目录

SKILL.md 是这个项目的另一半功能，不是可选文档：MCP 服务器负责存取，`SKILL.md` 负责让模型每完成一步真的去调 `tc_save`。

复制到客户端扫描的技能目录，目录名即技能名：

~/.agents/skills/ 是多个客户端共用的技能目录；客户端专属目录优先于它 —— 同名技能以客户端专属目录里的那份为准。OpenCode 等其它客户端放到它自己文档里的技能目录即可，规则不变。

tc-mcp --install-skill ~/.claude/skills/task-checkpoint

SKILL.md 是随包一起安装的（wheel 里的包数据），所以 pipx install 的用户不需要仓库，也不需要联网。目标已存在时会拒绝覆盖 —— 确实要覆盖加 --force；只想看内容用 tc-mcp --print-skill。

克隆了仓库的话，cp SKILL.md <技能目录>/ 效果一样。

Windows 路径形如 C:\Users\<你>\.claude\skills\task-checkpoint\SKILL.md。各客户端的技能目录可能不同，以它自己的文档为准；要求只有一条：文件落在技能目录下的 <技能名>/SKILL.md。重启客户端后生效。

自检（可选）

装完最快的一条，确认入口点活着、拿到版本号：

tc-mcp --version        # 版本号

tc-mcp --help # 所有开关

下面几条都要先克隆仓库 —— pip 装出来的包里没有 tests/ 和 tools/。

在克隆下来的仓库里跑一遍回归测试：

python -m unittest discover -s tests -p "test_*.py" -v

最后一行是 OK 就对了。整套测试（100 多个用例）跑一次的时间完全看环境：

同一套代码差了七十倍。开销集中在 git 子进程（refs/checkpoints/ 相关用例占大头）和静默期等待，对磁盘和杀毒的实时扫描极其敏感 —— 别把秒数当承诺，也别拿一个数字去对比另一台机器。

全部只用标准库，不需要 pytest；在 Python 3.10 上也能跑，只有读 pyproject.toml 的那几条会因为 tomllib 被跳过（3.11+ 全跑）。

仓库里还能跑真机端到端演练（起真 MCP 子进程、真杀进程、建约 190 MB 的重工作区、逐项核对"不动你 git"的承诺）：

python tools/drill.py

它跑完默认把场地删掉；想看场地就 TC_DRILL_KEEP=1 python tools/drill.py（演练有未通过项时也会自动保留，方便排查）。

确认 MCP 服务器能起来 —— 会回一行带 serverInfo 的 JSON：

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}' | python scripts/tc_mcp.py

从 pip 装的版本没有 scripts/，把上面那条改成 ... | tc-mcp（或 python -m tc_mcp）就行。

环境变量

使用限制

敏感文件：黑名单，盖不全

敏感文件不存内容、连哈希都不存，只能看出 mtime 和 size 变了没有。判定按路径匹配，所以两头都会漏：

• 漏判：名字无辜的凭据抓不到。config/database.yaml、docker-compose.yml、config.json 会被当普通文件明文存进 payload/。别把凭据放在被扫路径里；避不开时用 tc_init(exclude=[...]) 把整个目录排掉。
• 误拦：被误判为敏感的源码永远拿不到内容副本，回退时会静默跳过（只出现在 plan.unrestorable 里）。名单分两层就是为压低误拦。

拦的范围：

• 目录名（整个目录都不存） .ssh .aws .gnupg .docker .kube .env .envdir .secrets .tokens，或名字含 secret / credential / token 的目录。
• 无歧义文件名
• dotenv：.env .env.* *.env *.env.* .envrc
• 私钥：*.pem *.key *.p12 *.pfx *.p8 *.jks *.keystore *.kdbx *.ppk *.ovpn *_rsa *_dsa *_ed25519 *_ecdsa *_key
• 凭据：.netrc .git-credentials .npmrc .pypirc .pgpass .htpasswd .my.cnf my.cnf passwd shadow
• 云与基础设施：kubeconfig *.kubeconfig *.tfstate terraform.tfvars *.tfvars *.jwt
• 通配：credentials* creds* secret* secrets.json token token.json token.txt *.token *_token auth.json
• 框架配置：settings.py local_settings.py settings.xml wp-config.php web.config wrangler.toml .dev.vars
• 高歧义子串，只在文件名以配置类后缀结尾时才拦
• 子串：*secret* *password* *passwd* *credential* *api_key* *apikey* *token* *auth_token*
• 后缀：.json .yaml .yml .toml .ini .cfg .conf .config .properties .xml .txt .env .envrc .cnf .sh .ps1 .bat .cmd .sql .php
• 所以 prod_credentials.json 拦；src/password_policy.py、src/tokenizer.py、docs/secrets.md 不拦。

exclude 的匹配方式和内置名单一致：按单个名字段做 glob（目录名，或路径的第一段）。所以 exclude=["config"] 会排掉任意层级的 config/ 目录，但不能只排某个具体文件（要排 config/database.yaml 就得连 config/ 一起排）。带 / 的模式会被直接拒绝，不会静默失效。

这条能力不构成隐私保护或合规保证。 存档目录的访问权限由你自己管；别把未排除的凭据、令牌、私钥、个人资料放进被扫路径。

时间与粒度

• 静默期最长约 60 秒。文件一直在写时，中间那条记录标 partial: true。
• 进程突然死掉后、下次 tc_save / tc_capture 之前，最后那段改动只在 tc_resume 的未落档路径里，还不是一条变更层记录。

变更层只看 mtime+size

tc_capture 和后台线程用 mtime+size 判断变化。内容改了但 mtime 和长度都没变时（cp -p、rsync -t、tar -x 会保留 mtime），它不会觉得文件变了。

任务层 tc_save 默认按内容算 sha，不受此限；但 TC_SHA_REUSE=on 会把任务层也拉到同一判据上 —— 见下面那条。

回退

• 会一并还原文件权限位（POSIX 可执行位），不还原 mtime —— 把旧时间戳写回去会让 make 类工具误以为文件没变。注意：只改权限、内容没变时不会触发重写（回退只重写内容不同的文件），那种情况下权限位也回不去。
• 不能还原的文件会被跳过（敏感文件、超过 100 MB 未存内容、payload 已丢），其余照退；跳过的列在返回的 plan.unrestorable 里。预览和实际执行用同一份清单，所以一个 .env 不会让整次回退失效。
• 二进制能还原，但不能做行级 diff；不合并并发编辑。

大文件

不超过 100 MB 的文件原样按 sha 存进 payload/，相同内容只存一份；超过 100 MB 只记流式哈希和元数据，不保存内容，因而不能回退内容。

存档不会自动缩

旧变更层的内容会一直留着，用 tc_compress 手动回收。它的默认参数是保留 7 天，所以小工作区上默认调用往往是 converted: 0（什么都没回收）—— 返回值里带 keep_seconds / minimum / maximum / eligible / bytes_freed，看得出"为什么没回收"。想真的清就用小一点的 keep_seconds（步骤基线和 `recov