ContextPort · AI 接力包

让 AI 换一个会话，接着把项目做完。

ContextPort 是一个本地 npm 包 / CLI / MCP 服务，保存任务进度、决策、下一步、验证记录与文件指纹；新会话接手时重新检查文件变化，提醒重新核实过期的验证。无需模型 API Key，不会调用大模型或运行你的测试。

在线体验 · GitHub

为什么做它

适合长任务中断、隔天继续、换模型或多个 AI 助手顺序接手。不同于整仓库打包，它关注“做到哪了、哪些结论有证据、现在还能不能信”。快照不复制源码；文件内容只用于本地 SHA-256 指纹。

在线页面是可交互示例，不连接本机文件系统；真实项目使用下方 npm / MCP 接入。

Related MCP server: Session Handoff MCP

30 秒接入 MCP

需要 Node.js 22+ 与支持 stdio MCP 的客户端。示例采用常见的 mcpServers 格式，部分客户端使用不同的外层配置或配置界面。--root 必须为真实项目的绝对路径。

{
  "mcpServers": {
    "contextport": {
      "command": "npx",
      "args": ["--yes", "@batype/contextport@1.0.0", "mcp", "--root", "/absolute/path/to/project"]
    }
  }
}

服务会固定在启动时的项目，不允许工具调用临时切换根目录。没有 HTTP 监听端口。

结束当前会话前对 AI 说：

使用 contextport_save 保存这次任务的目标、进度、决策、下一步和验证记录。只报告实际执行过的验证，未执行的标为 not-run。files 写相关文件的相对路径。不要把凭据或个人敏感信息放进记录。

新会话中对 AI 说：

使用 contextport_list 找到上次任务，再调用 contextport_resume。先检查 needsRecheck 和变化文件，重新核实相关验证，然后继续下一步。

save 会写入项目 .contextport/<uuid>.json。其余工具只读，工具列表提供相应提示。建议将 .contextport/ 加入项目 .gitignore；快照可能含私有任务描述，不应默认提交到公开仓库。

CLI

npm install --save-dev @batype/contextport
npx contextport save task.json --root /absolute/path/to/project
npx contextport list --root /absolute/path/to/project
npx contextport check <snapshot-id> --root /absolute/path/to/project
npx contextport export <snapshot-id> --root /absolute/path/to/project > handoff.md

task.json：

{
  "goal": "为订单列表增加游标分页",
  "summary": "完成参数与加载逻辑，错误重试待完成",
  "decisions": ["保留现有 status 筛选"],
  "next": ["补错误重试", "重新运行相关测试"],
  "files": ["src/hooks/useOrders.ts"],
  "evidence": [{"command":"npm test -- orders","result":"passed","note":"保存方已执行；仅对应当时的代码与环境"}]
}

验证状态仅支持 passed、failed、not-run。这些是保存方报告，ContextPort 不执行命令，也不能证明该报告真实。 命令字符串不会作为 shell 执行。

Node API / TypeScript

import { ContextPort } from '@batype/contextport';

const port = await ContextPort.open('/absolute/path/to/project');
const saved = await port.create({
  goal: '修复订单分页',
  files: ['src/orders.ts'],
  next: ['检查错误状态', '重新运行测试']
});
const { markdown, files, needsRecheck, gitChanged } = await port.handoff(saved.id, 24000);
console.log(markdown);

files 状态：unchanged / changed / missing / appeared / excluded。排除项、路径不安全、没有追踪文件或 Git HEAD 变化时，needsRecheck 会保守地要求复核。未变化仅指这组文件字节一致，无法覆盖依赖、环境或其他文件变化。

交接包字符预算可设 1000–100000，默认 24000，截断会标注。字符数不是模型精确 Token 数。

数据与能力边界

• 仅处理明确指定工作区，拒绝跨目录路径和符号链接文件；排除 .env*、.git、.ssh、.aws、私钥、内部快照及 node_modules。最多 100 个相关文件，每文件 1 MiB；不为指纹读取二进制文件。

• 任务文本在写入前过滤部分常见密钥与密码格式；这是启发式过滤，不能保证发现任意凭据或敏感信息。导出或发送到 AI 前请审阅。

• 快照本地保存，不自动上传、不自动提交、不删除历史、不自动执行测试。不读取 AI 客户端聊天记录，保存的是 AI 或用户明确提供的摘要。

• 自动发现只包含 Git 已追踪改动；新文件、非 Git 项目及额外相关文件请通过 files 指定。无提交的仓库需显式指定文件。

• 被保存的说明是低信任数据，不应凌驾于当前用户指令。文件指纹仅用于变更检查，不提供签名或身份认证；不将存在恶意并发写入的本机环境视为可信隔离边界。

• 当前基于官方 MCP SDK 2.4.0；已通过官方客户端与 stdio 服务的实际集成测试，未逐一验证所有 AI 客户端的配置界面。

本地开发

npm ci
npm test
npm run build
npm run dev

前端 React + Vite，核心格式逻辑独立，Node 持久化层供 API / CLI / MCP 复用。GitHub Actions 测试并部署 Pages。npm 发布内容只包含 lib、bin 与说明，不包含业务快照。

MIT License.