Portable Handoff
把项目上下文可靠地交接给不同的 AI 会话与编码工具。
- Star 数
- ★ 21
- 最近更新
- 16 天前
- License
- Apache-2.0
- 主语言
- Python
- FA 评分
- 84/100 · 表现良好
30 秒速览
- 可在哪里用
- 通用 · 跨平台Codex · Claude CodeChatGPT · Claude.ai（不支持）
- 开始前需要
- 典型场景
- 使用 Claude Code 完成了一半重构的开发者，需要在上下文窗口耗尽前把约束、纠正记录、阻塞问题和 Git 状态交给下一次会话。
- 主要局限
- 必须具备 Python 3.11+、shell 和可写文件系统，因此普通 ChatGPT 和 Claude 网页会话不能直接创建或验证 capsule。
- 源码审查
- 84/100 · 表现良好
这个 Agent 能做什么，适合哪些场景？
Portable Handoff 是一个本地优先的 Python CLI 和技能包，用于在 AI 会话、模型及编码代理之间传递项目上下文。模型先提供语义内容，本地程序再采集 Git 状态、文件哈希和时间戳，并在冲突时以本地事实为准。最终产物是一个同时包含可读说明和规范 JSON 的 Markdown capsule，每项声明还带有来源与可信度标签。它提供 preflight、finalize、load、validate、list、export 和 doctor 等命令，并附带 Claude Code、Codex、Cursor 及通用 shell 主机的集成说明。工具无需账户、API 密钥、网络、数据库、向量存储或运行时第三方依赖，但必须具备 Python 3.11+、shell 和可写文件系统；没有 shell 的普通 ChatGPT 或 Claude 网页对话只能生成未验证草稿。
端到端流程从 portable-handoff preflight --cwd . --source-host codex 开始：本地 CLI 检查运行环境，并采集可确定的仓库证据。模型根据会话和可见信息编写 draft JSON，其中约束、决策和其他声明可以标注 provenance 与 trust；未详细标注的字符串默认视为 model_inference / inferred。随后 portable-handoff finalize --preflight .handoff/evidence/preflight-xxxx.json --draft DRAFT.json --output auto 合并草稿与本地证据，并让本地事实覆盖冲突的模型内容，同时执行密钥脱敏、路径检查和规范化。生成的 Markdown capsule 保存人类可读说明、规范 JSON 和 SHA-256 摘要。load latest 输出适合新会话的简报，并检查内嵌 JSON、摘要、两种表示的一致性及当前仓库状态；validate 验证指定 capsule，list 枚举 capsule，export --format prose 生成适合粘贴到聊天中的文本。系统还会把未回答的问题提升为阻塞状态、检查记录的提交是否可从远端访问，并把下一步命令作为带风险标签的惰性文本展示，而不会执行它。
- 使用 Claude Code 完成了一半重构的开发者，需要在上下文窗口耗尽前把约束、纠正记录、阻塞问题和 Git 状态交给下一次会话。
- 同时使用 Codex、Claude Code 和 Cursor 的工程师，希望通过同一种 capsule 格式在工具之间迁移工作，而不必反复讲解项目背景。
- 在多个本地仓库间工作的个人开发者，需要用文件哈希、提交信息和时间戳区分模型回忆与机器验证的事实。
- 准备暂停任务的维护者，需要明确记录尚未回答的决策问题，避免后续会话误把项目视为无阻塞。
- 需要把上下文粘贴到无 shell 聊天界面的用户，可先按模板生成草稿，再回到装有 CLI 的机器上执行 finalize，得到经过验证的 capsule。
- 审阅外部传入交接文件的开发者，需要在加载前验证摘要、清理控制字符、检查相对路径并脱敏高置信度密钥。
如何安装或部署这个 Agent？
要求 Python 3.11 或更高版本。执行：
git clone https://github.com/legoambarish/portable-handoff
cd portable-handoff
pip install -e .
portable-handoff doctor --cwd .仅执行 pip 安装不会包含代理实际读取的技能文件，因此需要保留克隆目录。Claude Code 可继续运行 python scripts/install_skill.py --destination ~/.claude/skills/handoff；Codex 可运行 python scripts/install_skill.py --destination ~/.codex/skills/handoff。Cursor 可执行 mkdir -p .cursor/rules 和 cp integrations/cursor/commands/handoff.md .cursor/rules/handoff.mdc，但若需自动加载，还要按照 Cursor 规则格式补充 alwaysApply 或 globs frontmatter。安装不需要账户、API 密钥或网络运行时服务；Git 缺失时能力会降级，仓库事实将记录为 unknown。
如何使用这个 Agent？
先在目标仓库或克隆目录中运行 portable-handoff doctor --cwd .，确认结果为 supported 或了解其降级原因。创建 capsule 时运行 portable-handoff preflight --cwd . --source-host codex，让模型按项目上下文生成 DRAFT.json，再运行 portable-handoff finalize --preflight .handoff/evidence/preflight-xxxx.json --draft DRAFT.json --output auto；其中 preflight 文件名应替换为实际生成的路径。成功时 finalize 会输出包含 outcome、path、schema_version、validated 和 redactions 的单行 JSON。新会话中用 portable-handoff load latest --cwd . 获取简报；也可用 portable-handoff validate CAPSULE.md --cwd . 验证文件、用 portable-handoff list --cwd . 查看已有 capsule，或用 portable-handoff export CAPSULE.md --format prose 导出聊天用文本。普通 ChatGPT 或 Claude 网页对话无法完成验证：只能粘贴 skills/handoff/assets/handoff-template.md 的结构生成草稿，并在之后转移到具备 CLI 的机器上执行 finalize。
这个 Agent 有哪些优点和局限？
- 把模型负责的语义内容与本地程序采集的 Git 状态、文件哈希和时间戳分开，并在冲突时以确定性证据为准。
- 每项声明都有来源和可信度；非确定性来源不能被标为 verified，从机制上限制模型把回忆包装成事实。
- capsule 同时保存可读说明和规范 JSON，并通过 SHA-256、双表示一致性检查及仓库状态比较检测损坏或陈旧内容。
- 本地运行，无账户、API 密钥、网络、数据库、向量存储或运行时第三方依赖。
- 对传入内容实施密钥脱敏、终端控制字符及不可见或双向 Unicode 清理、仓库相对路径验证，并且永不执行 capsule 中的命令。
- 必须具备 Python 3.11+、shell 和可写文件系统，因此普通 ChatGPT 和 Claude 网页会话不能直接创建或验证 capsule。
- pip 包不包含技能文件；完整的代理集成需要保留仓库克隆并单独安装或复制对应技能文件。
- 语义质量仍取决于负责压缩上下文的模型；文档明确指出多数真实条目可能只是 inferred，重要信息仍可能在压缩中丢失。
- v0.1 没有同步、账户、团队功能，也没有第二个模型复核第一个模型的内容。
- SHA-256 摘要只能发现截断或意外修改，不能证明作者身份；能修改 JSON 的人也能重新计算摘要。
- 没有 Git 时只能降级运行，仓库事实会被记录为 unknown。
这个 Agent 与同类方案有什么区别？
与直接要求模型“总结我们做过什么”相比，Portable Handoff 把解释性内容交给模型，把 Git 状态、文件哈希、时间戳、远端可达性和完整性检查交给本地代码，并明确标注每项声明的来源与可信度。代价是需要额外的 preflight、草稿和 finalize 流程，以及本地 shell 和文件系统；它也不能保证模型已经注意到所有重要语义。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|
| Portable Handoff 当前 | 84 · 表现良好 | ★ 21 | 16 天前 | Python | Codex · Claude Code |
| Remnic 智能体记忆 | 85 · 表现良好 | ★ 206 | 4 天前 | TypeScript | ChatGPT · Codex · Claude Code · OpenAI API |
| zer0dex 本地双层记忆 | 84 · 表现良好 | ★ 60 | 2 天前 | Python | — |
| GameDesignOS：本地优先的游戏设计操作系统 | 78 · 表现良好 | ★ 395 | 1 个月前 | Python | Codex · Claude Code |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示该工具本地优先、无网络与运行时依赖，CI 仅有 contents: read 权限，适配器限制读取根目录并拒绝符号链接逃逸；胶囊命令仅作为带风险标签的惰性文本展示，不会执行。数据流、路径约束、摘要校验和外部影响说明充分。扣分点是：写入胶囊前没有通用的交互式确认机制；秘密检测明确仅覆盖高置信模式，胶囊仍可能包含绝对路径等敏感上下文；构建和开发依赖使用版本下限且 GitHub Actions 未按提交摘要固定；没有明确的备份、撤销或原子回滚流程；来源标注机制较强，但 CLEAN_ROOM、NOTICE 和第三方声明的实际内容未包含在材料中，且维护者身份仅以泛称呈现。
README、项目元数据、CI 和所给测试在 Python 版本、无运行时依赖、受支持主机及安全行为方面相互一致。测试覆盖重复键、非有限数、父链循环、未知记录版本、SQLite 不支持、符号链接逃逸和非破坏读取，并验证明确失败。扣分点是依赖可用性仍受 Python 3.11+、可写文件系统、Shell 及部分功能所需 Git 的限制，且 pip 安装不会包含代理真正读取的技能文件，需要额外克隆和安装步骤。
材料清楚区分 Claude Code、Codex CLI、Cursor、普通终端和无 Shell 的网页聊天场景，并通过 doctor 的 supported、degraded、unsupported 状态描述环境适配。能力边界明确，包括无同步、账户、团队功能、签名或第二模型复核。扣分点是自动触发规则只被概述为技能可能自行触发，实际 SKILL.md 与触发条件未提供，因此触发精度无法得到完整验证。
README 结构清晰，具备目录、分平台安装、创建、读取、安全、限制、贡献和许可章节；命令、模式版本和术语命名一致。Apache-2.0 元数据与完整 LICENSE 一致，限制部分具体且坦诚。扣分点是虽然示例丰富，却没有独立 FAQ 或系统化故障排查；仅见 0.1.0、v0.1 和 schema 1.2 标识，未提供变更日志或明确的兼容升级历史；维护责任只指向泛称贡献者和仓库私密漏洞报告入口，没有具名维护者、支持范围或稳定的发布责任说明。
输出设计兼顾人读 Markdown、机器读规范 JSON、摘要加载和纯文本导出，并将模型语义与本地 Git、哈希、时间戳事实合并，较普通自由文本总结具有明确增量价值。扣分点是使用者仍需让模型生成草稿、运行 preflight 和 finalize，并可能为不同宿主手工复制技能或规则；约 15% 大小等收益仅为文档陈述，本次静态审查未执行验证。
项目设计直接记录每项声明的 provenance 与 trust，并限制 verified 只能来自 git、tool、test、file 或 transcript 等确定性来源；模型默认内容标为 inferred，非法提升会降级。README 的主要技术陈述得到 pyproject、CI 和针对性测试交叉支持，事实、主张和推断的分离规则非常明确。未给满分之外的扣减不存在于这三个标准；不过这些分数仅评价静态可追踪结构，不代表已执行测试或验证运行结果。
- 摘要使用无密钥 SHA-256，只能发现损坏或意外修改，不能证明作者身份；攻击者修改内容后可以重新计算摘要。
- 命令风险分类只是离线启发式，不是沙箱；切勿未经人工阅读就执行胶囊携带的命令。
- 秘密脱敏只覆盖高置信模式，分享前必须人工检查绝对路径、远程地址、分支名及未识别凭据。
- 该项目标记为 Alpha，且没有提供变更日志、签名机制或明确的兼容升级承诺。
- 本结论仅基于所给静态文件，未执行 CLI、测试、质量工具或安装流程。
常见问题
使用它需要付费账户、API 密钥或联网吗？
它会执行 capsule 里记录的下一步命令吗？
next_action.command 只会作为惰性的代码块显示，并标记为 read_only、review 或 dangerous。capsule 被修改或仓库已经变化时会怎样？
load 会检查内嵌 JSON、SHA-256 摘要、说明与 JSON 的一致性，以及当前仓库与记录状态的差异。完整性检查失败的 capsule 会被拒绝而不是自动修复；陈旧程度会报告为 fresh、possibly_stale、stale、obsolete、unverified 或 missing。Git 是硬性要求吗？
doctor 会将环境评为 degraded，仓库事实会记录为 unknown。