v0.1.7 — README sync to PyPI

代码没有改动。 这一版是为了把 README 同步到 PyPI。

PyPI 不允许修改已发布版本的长描述，所以 0.1.6 页面上挂的还是发布那一刻的 README。

README

安装节加了「方式三：用 npx 启动」（英文侧 Option 3）。npm 上确实有这个同名包，之前 README 一个字没提。写清了它的真实身份：只是启动器，本机仍然要先有 Python 包，否则它打印安装命令、以退出码 1 结束，而不是丢 traceback 出来。同时给了 npx 版的 mcpServers 片段，给只认 npm 式启动命令的客户端用。

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

标题下加了 npm 徽章（动态，跟随 npm 上的 latest）。

仓库结构里列上了 glama.json。

新增 glama.json

Glama 会自动索引 GitHub 上的 MCP server（站上已收录九万多个），但认领所有权需要在仓库根声明维护者：

{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": ["qddfxp"]
}

这不影响包内容，纯粹是目录站的所有权标记。

测试

127 个用例，本地与 CI 的四个 job 全部通过。这一版只动了 README 和一个新加的元数据文件，没有碰 scripts/。

v0.1.6 — Python 3.10 / 3.11 fix

代码有一个破坏性 bug 修复，建议升级。

0.1.5 在 Python 3.10 / 3.11 上装不起来

scripts/tc.py 里生成 handoff 的那段 f-string，表达式部分带着 '\u672a\u8bb0\u5f55' 这种反斜杠转义。Python 3.10 和 3.11 不允许 f-string 的表达式部分出现反斜杠（PEP 701 到 3.12 才放开），所以整个模块在这两个版本上直接 SyntaxError —— 而 pyproject.toml 声明的是 requires-python = ">=3.10"。

pipx install task-checkpoint-mcp 在 3.10 / 3.11 上会装出一个 import 就炸的包。0.1.6 修好了，行为与之前完全一致（handoff 输出逐字节相同）。

这个 bug 是 CI 第一次跑就抓到的。 上一次发版没有 CI，谁也没发现。

新增 CI

.github/workflows/ci.yml，四个 job：

• ubuntu × Python 3.10 和 3.13，windows × Python 3.13：跑全套测试
• release artifacts：构建、twine check、用 schema 校 server.json、断言 wheel 里带着 SKILL.md、真的装一遍验证 --install-skill 能落盘

requires-python 写 3.10 这句话，现在是被机器验过的 —— 之前只是一句话。

新增可移植性测试

PortabilityPromises.test_no_backslash_inside_fstring_expressions 用 AST 扫 f-string 表达式里的反斜杠。ast.parse(feature_version=(3,10)) 抓不到这个（实测 3.10 档照样报 OK），只能自己扫。

两处测试的环境依赖

• test_watch_errors_do_not_grow_stderr_linearly 在 GitHub 的 windows runner 上假失败。原因是它自己拼 tc._WATCH 的 key，而 TaskCheckpoint 构造时注册的是解析后的路径 —— Windows 上 resolve() 会换大小写或短名，拼出来是两个 key，而 _watch_once() 遍历全部 key，每行就重复写一遍。改为按路径选出真实那个 key 并断言唯一。
• test_server_survives_a_watch_tick 在 3.10 上报 ValueError: I/O operation on closed file：测试先手动 stdin.close() 再 communicate()，而 3.10 的 communicate() 会去 flush stdin。去掉手动 close。

两处都是测试自身的问题，产品行为没有变化。

README

自检的耗时说明换成 CI 实测的跨平台数据：ubuntu runner 4.7 秒 / windows runner 39.8 秒 / 本机 Windows 156～340 秒。同一套代码差七十倍，所以写明了「别把秒数当承诺，也别拿一个数字去对比另一台机器」——上一版单写一个数字，无论写哪个都不对。

测试

127 个用例，本地与 CI 四个 job 全部通过。

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

v0.1.5 — SKILL.md ships with the wheel

主要修一个 P1：SKILL.md 现在随包一起安装。

README 主推 pipx install task-checkpoint-mcp，但 SKILL.md 以前不在 wheel 里 —— 那一节给的 cp SKILL.md ... 对 pip 用户根本执行不了，而它是功能的一半（让模型每完成一步真的去调 tc_save）。

新增命令行开关

SKILL.md 作为包数据打进 wheel，装完直接可用，不需要仓库也不需要联网：

tc-mcp --install-skill ~/.claude/skills/task-checkpoint   # 写进技能目录
tc-mcp --print-skill                                      # 打到 stdout
tc-mcp --skill-path                                       # 打印路径，配合 cp
tc-mcp --version
tc-mcp --help

--install-skill 对已存在的文件会拒绝覆盖，要覆盖加 --force。

兼容性：不带参数照旧进 MCP stdio。 认不出来的参数只会在 stderr 提一句然后继续按 MCP 启动，所以客户端多传参数不会让服务器起不来。

README

• 装 SKILL.md 那一步改成 tc-mcp --install-skill，不再依赖 raw.githubusercontent.com
• 耗时说明改成实测区间：本机实测 156～340 秒（C 盘全新 clone 156 秒，E 盘 166～340 秒），并注明"别把秒数当承诺"。上一版写的「28 到 35 秒」我用文档里那条命令复现不出来，五次测量都在 156 秒以上
• 用例数不再写死具体数字（每加一个测试就过期一次），改成「100 多个用例」，耗时同样给区间
• 「自检」一节标明测试和演练都需要先克隆仓库 —— pip 装出来的包里没有 tests/ 和 tools/
• 新增「配置文件放哪」：各客户端配置文件位置与顶层键，含两个坑（VS Code 的顶层键是 servers 不是 mcpServers；Codex 用 TOML）
• 新增导航行、「第一次跟 Agent 说什么」、结尾的参与与 License 两节

新增一致性测试与 CI

tests/test_packaging_consistency.py 钉住四件事：三个文件的版本号必须一致、server.json 指向真实的包与仓库、README 里那行 <!-- mcp-name: ... --> 必须还在（注册表靠它验所有权）、npm 启动器与 PyPI 包同名是有意的。

.github/workflows/ci.yml：ubuntu 上跑 Python 3.10 和 3.13、windows 上跑 3.13；另外构建一次、twine check、用 schema 校 server.json、断言 wheel 里带着 SKILL.md、并真的装一遍验证 --install-skill 能用。

版本号散在三个文件、registry 一度停在旧版本，就是这类漂移的实例 —— 现在改漏一处 CI 就红。

测试

126 个用例全部通过（本机 184.8 秒）。

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

npm

cli.js 加了 --help / --version（不再需要本机有 Python），其余参数会透传给 Python 服务器（所以 npx -y task-checkpoint-mcp --install-skill <目录> 也能用）。npm/README.md 里点明了它与 PyPI 包同名但是两回事。

v0.1.4 — README sync to PyPI

代码没有改动，这一版是为了让 PyPI 上的 README 跟上。

PyPI 不允许修改已发布版本的长描述，所以 0.1.3 页面上挂的还是发布那一刻的 README。0.1.4 把最新的那份带上去了。

README 变化

加了标题下的导航行（快速开始 / 工具 / 客户端配置 / 使用限制 / English）。锚点是拿 GitHub 渲染后的实际 heading id 核对过的。

新增「配置文件放哪」 —— 各客户端配置文件位置与顶层键。两个坑写进去了：

• VS Code 的顶层键是 servers，不是 mcpServers。 直接抄 README 里的配置到 VS Code 里不会生效，也不报错，就是没反应。
• Codex 用 TOML 不是 JSON，配置写在 ~/.codex/config.toml 的 [mcp_servers] 段。

快速开始加了第五步「不用记工具名，直接说人话」 —— 给了一句可以直接复制给 Agent 的 prompt。原来只列了四个调用名，读者得自己翻译成"我该怎么跟它说话"。

结尾补了「参与」和 License 两节，并写明项目只承诺标准库：不接受任何新增依赖，测试依赖也不行（测试用 unittest，不用 pytest）。

一处数字改正

README 里写的测试用例数是 117，实际是 118 —— 上一版给 tests/test_tc_regressions.py 加过一条「版本号必须来自 pyproject」的回归，数字没跟着更新。已改。

顺带把耗时说明改准：多次实测在 177 秒到 340 秒之间浮动（原来是固定写「340 秒」），所以现在写的是 3～6 分钟，并说明波动来自 git 子进程和静默期等待。

测试

118 个用例，本次发版前实测 177.574 秒，OK。

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

渠道

PyPI、npm 都是 0.1.4；MCP Registry 的 io.github.qddfxp/task-checkpoint-mcp 同步到 0.1.4。

v0.1.3 — first PyPI release

首次发布到 PyPI。

pipx install task-checkpoint-mcp

相对 0.1.2 的改动

修了一个会骗人的 bug。 scripts/tc_mcp.py 把版本号硬编码成 0.1.2，所以包升级之后客户端 initialize 拿到的 serverInfo.version 和实际装的版本就不是一回事了，而且不改那一行永远不会有人发现。现在从 pyproject.toml 读，装成包读不到 pyproject 时退回包元数据。

新增第二个 console script task-checkpoint-mcp。 uvx 是按「包名 = 命令名」找可执行文件的，只有 tc-mcp 的话 uvx task-checkpoint-mcp 直接找不到命令，而 Registry 客户端正是这么调 PyPI 上的 stdio server。

README 重写。 加了快速开始、徽章（license / python / dependencies / MCP）、四条铁律，以及完整英文版。补上 <!-- mcp-name: io.github.qddfxp/task-checkpoint-mcp --> —— 官方 MCP Registry 就是靠这行校验 PyPI 包所有权的。

新增 server.json，官方 MCP Registry 的发布元数据。

新增 npm 启动器包 task-checkpoint-mcp（npx -y task-checkpoint-mcp）。它只是个壳，服务器本体仍然是这个 Python 包；本机没有 Python 包时它会打印安装指引并以 1 退出，而不是丢一堆 traceback。

新增一条定向回归测试，钉住「版本号必须来自 pyproject」，防止再出现两处维护。定向回归 8 → 9 条。

测试

109 条验收测试 + 9 条定向回归，共 117 条，全部通过。本机 Windows 实测约 5 分钟（开销集中在 git 子进程和静默期等待）。

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

v0.1.2

修复上一版的交付缺陷，并把文档里说过但做不到的两件事补成真功能。

测试

• 恢复完整验收套件 tests/test_tc.py（109 条：回退安全、并发锁、git ref 可达性、日志不膨胀、每个 MCP 分支的返回字段完整性、compress 边界、打包契约）
• 上一版新增的 4 条定向回归移到 tests/test_tc_regressions.py 并补到 8 条
• 两文件一起跑：117 条，约 30 秒全过

新能力

• tc_init 新增 exclude 参数：把整个目录排除出存档，这是敏感文件名黑名单的正式逃生口。模式按单个名字段 glob 匹配，含 / 的模式会被拒绝而不是静默失效
• 新增 tc_import 工具：tc_export 的交接包现在能在另一个目录/机器上通过 MCP 导入，不必手写 Python；重复导入返回工具级错误而不是 internal error

文档

• 新增「返回值里几个值得看的字段」：handoff / drift_paths / idempotent / recovered / plan.unrestorable / waiting / partial
• 修正两处「说了但做不到」：state.exclude（无任何工具可设）与交接包导入（无对应工具）
• 客户端技能目录按客户端分行（Claude Code / Codex / ZCode / 跨客户端共用），去掉 clone 下来并不存在的 dist/
• 引号风格与 SKILL.md 统一

工具数 9 → 10，服务器版本号同步为 0.1.2。

v0.1.1

首个可用版本。

• 9 个工具：tc_init / tc_save / tc_capture / tc_show / tc_restore / tc_resume / tc_switch / tc_export / tc_compress
• 步骤存档 + 文件变更自动记录 + 任意步回退（含误操作撤销）
• 不修改用户 git 历史，只额外建 refs/checkpoints/... 引用
• 只用 Python 标准库，Python 3.10+

修复（相对最初的 0.1.1 构建）：

• tc_restore 不再删除新出现的敏感文件，改为列入 plan.unrestorable
• tc_save 幂等判定纳入 conclusion / next / verified / open_questions / description
• tc_compress 保护整个 store 内其它任务引用的 payload

包含 wheel 与 sdist 两种安装产物。