Portable Handoff

这个 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 生成适合粘贴到聊天中的文本。系统还会把未回答的问题提升为阻塞状态、检查记录的提交是否可从远端访问，并把下一步命令作为带风险标签的惰性文本展示，而不会执行它。

1. 使用 Claude Code 完成了一半重构的开发者，需要在上下文窗口耗尽前把约束、纠正记录、阻塞问题和 Git 状态交给下一次会话。
2. 同时使用 Codex、Claude Code 和 Cursor 的工程师，希望通过同一种 capsule 格式在工具之间迁移工作，而不必反复讲解项目背景。
3. 在多个本地仓库间工作的个人开发者，需要用文件哈希、提交信息和时间戳区分模型回忆与机器验证的事实。
4. 准备暂停任务的维护者，需要明确记录尚未回答的决策问题，避免后续会话误把项目视为无阻塞。
5. 需要把上下文粘贴到无 shell 聊天界面的用户，可先按模板生成草稿，再回到装有 CLI 的机器上执行 finalize，得到经过验证的 capsule。
6. 审阅外部传入交接文件的开发者，需要在加载前验证摘要、清理控制字符、检查相对路径并脱敏高置信度密钥。

如何安装或部署这个 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 有哪些优点和局限？

这个 Agent 与同类方案有什么区别？

与相关度最高的同类 agent 并排比较关键指标。

FollowAgents 如何评估这个 Agent？

[![FARS 评测](https://followagents.com/badge/portable-handoff.svg?lang=zh)](https://followagents.com/zh/agents/portable-handoff)

<a href="https://followagents.com/zh/agents/portable-handoff"><img src="https://followagents.com/badge/portable-handoff.svg?lang=zh" alt="FARS 评测"></a>

最近版本

来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。

1. v0.1.0-alpha 预发布 2026-08-20
   发布说明摘录

   First public release. Portable Handoff compacts an AI coding session into one Markdown file: the active model writes the goal, decisions, corrections, and next action, and a local script writes the parts a model shouldn't be trusted to remember on its own: the current Git branch and commit, whether that commit was ever pushed anywhere, and file hashes. Every claim carries a label for where it came from and how much to trust it, and a claim marked verified requires a deterministic source, never just the model's word. Standard library only, no runtime dependencies, offline by default. No …

   在 GitHub 查看 ↗

常见问题