Handover

Handover MCP

在 Claude Code、Codex、Cursor、Gemini CLI、人员和服务 Agent 之间转移当前工作，同时保留决策、文件、历史记录和作者信息。

Handover 通过托管的模型上下文协议服务、无依赖的 CLI 和八个开源 Agent Skills，为人员和 AI Agent 提供共享的版本化上下文。此仓库是这些接口的公开源码、发现、安装和连接记录。

研究与证据

Handover 研究与证据索引汇集了开放的连续性基准测试、Reporter 迁移实地报告、交接连续性记录，以及可运行的续接演示。研究结果与其方法、源素材、第一方关系和实质性局限一并呈现。

版本化的 research/v1/ 套件为 Agent 和研究人员提供稳定的 JSON 索引、JSON Schema、引用元数据和有限范围的 Markdown 摘要。此套件由 Handover 和 44pixels 作为第一方出版物发布，旨在供人查阅和复用，并非独立验证。

• 供人阅读的研究索引
• 供 Agent 读取的生产索引
• 版本化的仓库索引
• 引用元数据
• 运行并提交独立基准测试结果

查看完整的交接过程

公开的续接演示从两种视角展示同一工作流：交互式人工视图和可供 Agent 读取的记录。其中包含 Markdown、SQL、JSON、一份可视化素材、三个可追溯来源的修订、一条人工审核备注，以及下一个 Agent 的处理结果。无需账户。

• 交互式演示
• 在你的工作区继续演示
• 演示工作流与验证说明
• 供 Agent 读取的清单
• 原始 Markdown
• 原始 SQL
• 证据 JSON

构建私密交接提示词

AI 交接提示词生成器可将未完成的工作转换为单独的记录提示词和接收者提示词，无需注册账号。草稿字段仅保留在浏览器标签页中，不会发送到分析系统，也不会作为服务端草稿存储。

接收者提示词要求下一位执行者检查证据、区分已验证和未验证的状态、找出阻碍因素，并在继续之前说明一项范围明确的下一步操作。复制或下载 Markdown 记录，或者将同一份私密草稿带入预填内容的首次交接。

• 打开私密提示词生成器
• 查看原始 Markdown 示例
• 确定何时 HANDOFF.md 已足够

从 Claude Code 迁移到 Codex

对于一次性迁移受支持的 Claude Code 设置、项目、记忆和近期聊天记录，Codex 内置的导入功能是首选。如果 Claude Code 和 Codex 将交替处理未完成的工作，并需要共享工件、独立身份、审查和修订历史记录，则使用 Handover。

Claude Code 到 Codex 的迁移方案包含准确的发送方检查点、双主机服务凭据设置、接收方验证、乐观并发继续操作、撤销测试和通过标准。渲染后的指南说明何时使用原生导入，何时使用持久交接。

执行经过审查的 MCP 交接

演示展示了已完成的记录。端到端 MCP 交接流程会通过不同的已认证身份测试工作流本身：

1. 验证发布者；
2. 发布 Markdown、SQL 和 JSON；
3. 读取所有工件；
4. 以另一身份审查确切证据；
5. 使用乐观并发发布修正内容；
6. 根据修正后的版本解决问题；以及
7. 证明新的后续执行者无需原始聊天记录即可继续工作。

该流程还会测试拒绝访问、只读、版本过期和凭据撤销等路径。查看渲染后的指南了解原因，或者先通过安装流程连接 Agent，再运行仓库流程。

使用 AI Agent 交接清单

对于较小规模的本地交接，请从 Markdown 清单开始。它会记录目标、当前状态、决策、证据、约束、下一步操作和责任归属，并要求接收方读取当前版本、打开证据、复现一项有意义的结果，然后将交接标记为已通过或受阻。

渲染后的清单和常见问题会解释每个验证步骤。原始模板无需 Handover 即可使用；当多个执行者需要经过身份验证的访问、不可变版本、搜索、批注或可审计的责任归属时，请使用托管服务。

测试公司 AI 上下文就绪情况

在将公司知识连接到多个人员和 Agent 之前，请使用 公司 AI 上下文就绪情况检查清单。 该清单区分已批准的来源知识与持续变化的记录，盘点人员和服务身份，声明公司与工作区边界，并以一个由两个人员、两个 Agent 参与的试点收尾。

试点的标准有意设置得比导入数量更严格：它会验证授权检索、可追溯的修订、人工审核、拒绝搜索、Agent 撤销权限，以及新会话续接。来源关联的架构 指南 解释了搜索索引、私有模型记忆和公司规范记录各自承担不同职责的原因。

使用开放的交接格式

交接连续性 记录 是一种与平台无关的 JSON 格式，用于记录其他人员或 AI Agent 验证并继续工作所需的状态。它记录目标、已验证与未验证的状态、决策、证据、约束、下一步行动、所有权和待审事项，但不规定传输、路由、身份验证或存储方式。

protocol/v1/ 目录包含：

• JSON Schema Draft 2020-12 契约；
• 有效的库存报告示例；
• 一个无依赖的 Node.js 一致性检查器；以及
• 生产者、接收方、范围和安全要求。

node protocol/v1/validate.mjs protocol/v1/example.json

MCP 可以公开用于读取和写入记录的工具。A2A 或编排框架可以对其进行路由。Git 或 Handover 可以存储它。

连接

规范的 Streamable HTTP 端点为：

https://handover.sh/api/mcp?profile=core

推荐的核心配置文件公开了 17 个工具，适用于日常身份管理、搜索、检索、审核、续接、发布和可移植性工作流。使用 https://handover.sh/api/mcp?profile=native 可访问 Handover 的全部 27 项第一方操作。未指定参数的 https://handover.sh/api/mcp 端点保留全部 55 个工具以及 Reporter 别名，以兼容现有集成。

该端点无需账户即可公开 MCP 握手信息和工具架构，便于客户端和目录在连接前验证兼容性。工具调用仍受保护；如果没有有效的人员或服务凭证，端点会返回 Handover 的 OAuth 资源质询。

交互式 MCP 主机使用 Handover 的第一方 OAuth 流程：标准发现、动态客户端注册、PKCE、短期访问令牌和轮换刷新令牌。主机会在浏览器中打开 Handover；请以本人身份登录，查看所请求的权限，并批准连接。Handover 会在每项可归属的操作中记录你的人员身份。

无人值守的运行器和不支持 OAuth 的主机，应使用在 Workspace or Company -> Agents 下创建的独立命名、设定范围的服务凭证。人员和服务身份仍可独立追溯和撤销。

完整的设置、身份检查、双 Agent 连续性测试和故障排除流程，请参阅 CONNECTING.md。

Codex

codex mcp add handover --url https://handover.sh/api/mcp?profile=core
codex mcp login handover

Claude Code

claude mcp add --transport http --scope user \
  handover https://handover.sh/api/mcp?profile=core

Gemini CLI

gemini mcp add --transport http --scope user \
  handover https://handover.sh/api/mcp?profile=core

Cursor

将以下内容添加到 .cursor/mcp.json。Cursor 会发现 Handover 的授权服务器，并在连接启动时提示你通过浏览器登录：

{
  "mcpServers": {
    "handover": {
      "url": "https://handover.sh/api/mcp?profile=core"
    }
  }
}

Cline

打开 Cline 的 MCP 向导：

cline mcp install handover --transport http https://handover.sh/api/mcp?profile=core

选择 Remote (HTTP) 和 Static headers，然后在 Cline 的私有请求头提示中输入范围受限的服务 Agent 凭证。面向 Agent 的 llms-install.md 包含精确的配置、身份检查、安全的首次写入、双 Agent 续接测试和撤销流程。 请使用 Cline 官方设置 页面 完成完整的 Handover 流程。请勿在聊天中粘贴真实凭证，也不要提交 Cline 的私有 MCP 设置。

命令行客户端

无需依赖的 Handover CLI 支持在终端中执行相同的持久化工作流：

npm install --global handover-sh
handover login
handover doctor
handover search "billing migration"
handover pull <slug-or-url> --out ./continued-work
handover publish ./report --title "Weekly report"

已发布的软件包源码和元数据位于 cli/。当 npm 不适用时，仍可使用经过审计的直接安装程序：

curl -fsSL https://handover.sh/install.sh | sh

软件包版本基于此公开仓库构建。RELEASING.md 介绍了引导和可信发布流程。

handover doctor 是只读连接检查。它会验证已配置的端点、服务端解析的身份、工作区、角色、权限范围以及一个受保护的上下文请求，且不会打印凭证或更改交接内容。请在 Agent 首次写入前，使用完整验证清单。

Agent 技能

使用开放的 Agent Skills 格式，将可复用的 Handover 工作流安装到兼容的编码 Agent 中：

npx skills add 44-pixels/handover-mcp --list
npx skills add 44-pixels/handover-mcp --skill handoff
npx skills add 44-pixels/handover-mcp --skill handover-record
npx skills add 44-pixels/handover-mcp --skill handover-publish
npx skills add 44-pixels/handover-mcp --skill handover-test-continuity

公开集合包括以本地优先的会话交接、用于创建和验证机器可读记录的技能、验证连接、发布上下文、恢复工作、审查与修订版本关联的反馈、测试完整的多身份连续性，以及管理 Agent 访问权限的技能。请浏览 skills.handover.sh 上的目录，或查看 skills/ 中的源代码。该集合也已编入 Skills.sh 目录。目录按交接阶段组织技能，为每个工作流提供通俗易懂的起始请求，并通过其机器可读索引列出准确的 MCP 工具和 CLI 命令。

该运行时也已独立列入 官方 MCP Registry 中的 sh.handover/handover。

Agent Skills 和 MCP 指南介绍了可移植工作流说明与经过身份验证的运行时能力之间的界限。原始端到端工作流专为 Agent 直接检索而设计。

如需针对特定宿主进行安装，请参阅经过测试的 Claude Code、Codex、Cursor 和 Gemini CLI 指南。其中的原始验证清单将文件安装与宿主发现、技能激活、经过身份验证的 MCP 身份、读回、拒绝访问和跨宿主继续工作分别列出。

要发布使用 Handover 的工作流，请从 Agent Skill 开发工具包、贡献者约定和入门技能开始。将入门技能复制到新的 skills/<name>/SKILL.md；该模板有意不使用保留文件名，以免注册表将其误认为可安装的技能。社区提交内容会保留其发布者和来源归属；收录到目录中不会扩大 Handover 的访问权限，也不会取代对源代码的审查。

在测试经过身份验证的工作流之前，请先验证本地约定：

node templates/handover-skill/validate.mjs skills/<name>/SKILL.md

通过此验证器只能证明文件符合约定，不能证明宿主发现、MCP 身份验证、权限、读回或拒绝访问行为符合要求。开发者工具包会明确列出这些运行时检查。

开放连续性基准测试

AI 交接连续性基准测试 用于测试后续模型能否从对话记录、压缩记忆或结构化交接中恢复目标、当前状态、决策、证据、约束、下一步行动、负责人和待解决问题。

首轮双系统试点中，结构化交接得分为 79.45，对话记录得分为 76.67，压缩记忆得分为 45.00。这是一项规模较小、由作者设计的试点，而非模型排行榜。公开的 benchmark/ 目录包含数据集、答案、无依赖评分器、严格格式的提交、确定性结果、局限性以及全部 18 份原始响应正文。请使用已发布的 CITATION.cff、 citation.bib 或精简的 summary.csv，而不要从页面上转录数值。

cd benchmark/v1
node run.mjs --validate-scorer
node run.mjs --prompts ./prompts

Agent 能做什么

已连接的 Agent 可以：

• 使用 handover.whoami 验证当前身份、组织、工作区和权限范围；
• 搜索公司或个人背景信息；
• 查看某个确切且不可变的修订版本；
• 读取附加的 Markdown、HTML、SQL、JSON、代码、图像和其他文件；
• 检索讨论和以修订版本为依据的批注；
• 创建新的交接或继续现有交接；
• 添加、编辑、解决和回复审阅评论；
• 在审计记录中保留经过身份验证的人类或服务身份。

服务端绝不会要求 Agent 在工具输入中提供作者身份。作者身份来自经过身份验证的凭据。

验证连接

在开展实际工作前，请让已连接的宿主执行以下调用：

1. 不带参数调用 handover.whoami，并确认返回的人员或具名服务 Agent、组织、工作区、角色和权限范围。
2. 使用 { "query": "" } 调用 handover.search，并确认它只返回该身份有权访问的背景信息。
3. 在创建或继续工作前，读取一个已知交接及其附件。

正常工作的连接会列出 Handover 的工具，且不会出现 JSON 或登录错误；会将预期身份保留为作者；并会在撤销 OAuth 授权或服务凭据后立即停止工作。

服务 Agent

工作区所有者在 Handover 中创建服务 Agent，并仅授予该角色所需的权限范围。将凭据存储在 HANDOVER_TOKEN 中；不要将其放入仓库，也不要放入提交到源代码管理中的 MCP 配置。

export HANDOVER_TOKEN='hnd_tok_...'
codex mcp add handover \
  --url https://handover.sh/api/mcp?profile=core \
  --bearer-token-env-var HANDOVER_TOKEN

发现与文档

• 无需登录的延续演示
• AI Agent 交接清单
• 公司 AI 上下文就绪情况清单
• 共享知识库架构指南
• 端到端审核式 MCP 交接
• 已渲染的 MCP 交接指南
• 安装与特定主机的设置
• Claude Code、Cursor 和 Codex 的 MCP 记忆设置
• 原始跨主机设置与连续性测试
• 将上下文从 Claude Code 转移到 Codex
• 已渲染的 Claude Code 到 Codex 指南
• 连接与验证操作手册
• MCP 工作流指南
• MCP OAuth 与服务账号
• 在 AI 编码 Agent 之间保留上下文
• 迁移静态报告文件夹
• Glama 托管连接器
• 机器可读的主机配置方案
• MCP 服务清单
• Agent 工具清单
• OpenAPI 文档
• Agent 可读知识语料库
• 安全模型

源码与支持

托管版 Handover 应用的源码保存在私有仓库中。 此公开仓库包含 MCP 连接记录、设置文档，以及无依赖 CLI 的源码， 不包含托管服务的实现。

如需报告连接或文档问题，请通过 GitHub Issues 提交。报告 安全问题请使用 SECURITY.md 中的流程。