Portable Handoff 是一个本地优先的命令行工具，目标是在不同 AI 聊天、模型和编码代理之间保持相同的上下文，避免每次切换 AI 工具时重新解释项目。
用途 当与编码代理工作一段时间后，上下文窗口填满或切换工具，下一次会话往往从零开始。直接让模型“总结我们做了什么”会得到读起来通顺但可能悄悄编造内容的摘要。Portable Handoff 改为写入一个胶囊（capsule）：一个 Markdown 文件，其中模型提供含义，本地代码提供事实。Git 状态、文件哈希和时间戳来自本机，而非模型的回忆。每条声明都标注来源和可信度。
主要能力
- 生成胶囊：模型根据所见内容写出草稿 JSON，本地代码收集事实并合并，在两者不一致时以本地事实为准。
- 加载胶囊：加载时检查嵌入的 JSON、SHA-256 摘要、两半内容的一致性，以及当前仓库与记录内容的匹配情况。过期状态返回 fresh、possibly_stale、stale、obsolete、unverified 或 missing。完整性检查失败的胶囊会被拒绝，绝不修复。
- 状态提升：草稿中未回答的问题会被提升为 blocked 状态，而非 in_progress。
- 发布警告：来自 git branch --remotes --contains，而非模型编写。
- 信任标签：trust: verified 需要确定性来源（git、tool、test、file、transcript），否则降级为 claimed，防止模型将回忆洗白为事实。
- 安全处理：导入的散文视为数据而非指令；来自胶囊的路径在使用前验证为仓库相对路径；next_action.command 以惰性围栏文本打印并标注 read_only/review/dangerous，绝不执行；文本剥离终端控制序列和不可见或双向 Unicode；高置信度机密在哈希或写入前被脱敏，报告保留计数和类别但不保留匹配值。
- 摘要不证明作者身份：它是无密钥 SHA-256，能捕获截断和意外编辑，但任何编辑 JSON 的人都可以重新计算。
使用方式
- 克隆仓库。仅 pip install 会得到 CLI，但代理实际读取的技能文件位于同一克隆中，pip 不会打包它们。
- 需要 Python 3.11 或更新版本。无运行时依赖、无网络访问、无账户、无 API 密钥、无数据库、无向量存储。先运行 doctor 检查当前环境，输出 supported、degraded 或 unsupported。
- 技能安装位置：Claude Code 为 ~/.claude/skills/（机器范围）或 .claude/skills/（单项目）；Codex 为 ~/.codex/skills/ 或 .codex/skills/；Cursor 的代理已有 shell，可直接运行 CLI 命令，也可将现有指令转为项目规则。
- 对于没有 shell 的环境（如纯 ChatGPT 或 Claude 网页对话），无法写入文件或运行 doctor，因此没有可安装内容。可将 skills/handoff/assets/handoff-template.md 的形状粘贴到聊天中，让模型填写并保存返回内容。这是草稿而非胶囊，没有摘要和已验证的仓库事实。之后可在有 CLI 的机器上运行 finalize 得到真正的胶囊。
- 让代理自行安装：将指定提示粘贴到 Claude Code、Codex、Cursor 或其他有 shell 的工具中，其中包含克隆、pip install -e .、运行 python scripts/install_skill.py --destination 指向技能目录，以及运行 portable-handoff doctor --cwd . 并原样粘贴输出。
- finalize 打印一行可引用的内容。草稿中的声明列表可接受裸字符串，默认 model_inference / inferred，模型只需为少数值得更强标签的项花费 token。
- 胶囊以散文和规范 JSON 两种形式保存内容，load 和 export 各给出一半。
适用场景
- 在 Claude Code、Codex、Cursor 或任何终端中工作。
- 需要在不同 AI 工具之间迁移编码会话上下文。
- 需要可验证的仓库事实而非模型回忆。
限制
- 需要文件系统和 shell。不适用于纯 ChatGPT 或 Claude 网页对话。
- 斜杠命令注册因宿主而异；工件和 CLI 在各处行为相同。
- 语义质量取决于执行压缩的模型。实际胶囊中大多数条目最终标记为 inferred，诚实但单薄；胶囊质量取决于模型注意到什么。压缩会丢失信息。Git 事实证明仓库状态，不证明任何人说了什么。
- v0.1 没有同步、账户、团队功能，也没有第二个模型检查第一个模型的工作。
- 质量测试工具 tests/quality/evaluate_quality.py 运行十二个场景通过真实管道，并经过变异测试，能说明管道保留了给定内容，但不能说明模型提供了多少内容。
- 许可证为 Apache-2.0。提交需要 Signed-off-by 行（git commit -s）并遵循 DCO。
