Context Capsule

Context Capsule

切换编码 Agent，不丢失上下文。

Context Capsule 是一款开源、本地优先的 Agent Skill，可将正在进行的编码任务从 Codex 交接给 Claude Code、Cursor、其他 Agent，或未来的自己。它会记录最有用的最少信息：仓库身份、决策、约束、验证情况、阻碍事项，以及一个具体的下一步操作。

接手的 Agent 会先检查交接内容是否仍然适用，再决定是否信任它。

网站 · Skill 源码 · 当前方向 · 交接示例 · 可选的托管 API · ProofSlip

安装 Agent Skill

npx skills add Johnny-Z13/context-capsule --skill contextcapsule-handoff

此 Skill 使用开放的 SKILL.md 和一个无依赖的 Node 助手。它适用于 Codex、Claude Code、Cursor，以及其他支持 Agent Skills 格式的工具。

提示词示例：

Create a Context Capsule before I switch this task from Codex to Claude Code.

Resume from .contextcapsule/latest.json, but check whether it is stale first.

本地工作流无需账户、API 密钥、数据库或上传。

记录的内容

coding-handoff/v1 格式包含：

分类	解答的问题
目标	我们要实现什么结果？
当前状态	哪些已完成、部分完成、未经验证或不在范围内？
仓库	这里描述的是哪个远程仓库、分支、HEAD 和工作区指纹？
决策	下一个 Agent 必须保留哪些选择？
约束	哪些事情不能做，或不能想当然？
验证	观察到或仅被报告的命令及结果是什么？何时发生？
阻碍事项	还有什么需要授权、凭据、其他人员或外部状态？
下一步操作	接下来应该执行哪个范围明确的单一步骤？
参考资料	哪些 ProofSlip 证明、问题或拉取请求与此相关？

它是一份交接记录，不是对话记录、通用记忆库、自主编排器，也不是事实声明的权威来源。

本地工作流

此 Skill 通常会为你执行以下命令。这里列出这些命令，是为了让其行为可供检查。

1. 捕获仓库状态

node .agents/skills/contextcapsule-handoff/scripts/contextcapsule.mjs \
  capture --repo /path/to/repository

捕获操作为只读。它会记录经过清理的仓库元数据和数量受限的已更改文件名，不会读取或复制源文件内容。

2. 创建交接记录

按照格式参考准备语义输入文件，然后：

node .agents/skills/contextcapsule-handoff/scripts/contextcapsule.mjs \
  create \
  --repo /path/to/repository \
  --input /path/to/handoff-input.json

默认输出：

.contextcapsule/
├── latest.json
├── latest.md
├── previous.json   # when an older capsule existed
└── previous.md

只有在用户批准写入位置后，才能运行此助手。它不会自动编辑 .gitignore。

3. 安全恢复任务

node .agents/skills/contextcapsule-handoff/scripts/contextcapsule.mjs \
  resume \
  --repo /path/to/repository \
  --capsule /path/to/repository/.contextcapsule/latest.json

结果可能是以下之一：

• compatible — 仓库身份和记录的状态仍然一致。
• stale — 仓库相同，但分支、HEAD、工作区、文件或有效期已发生变化。
• mismatched — 交接记录描述的是另一个仓库。
• unverifiable — 无法检查当前仓库状态。

过期的 Capsule 仍可保留目标、决策和约束。继续之前，请重新检查已更改的文件、验证情况、阻碍事项和下一步操作。

隐私与信任边界

• 默认使用本地模式。常规工作流不会连接 Context Capsule 服务器。
• 写入 .contextcapsule/、更改忽略规则或上传之前，Agent 会先征求同意。
• 自动捕获只记录文件名和 Git 元数据，不记录文件内容。
• 写入 Capsule 之前，会拒绝符合常见凭据模式的内容。
• 机密检测只是防护措施，并非万无一失。分享之前请检查交接记录。
• 托管 Capsule 对任何持有其 URL 的人公开，且需要明确同意。
• Capsule 只报告上下文，不能独立证明某条命令、部署或发布确实发生过。

默认情况下，本地和托管内容的有效期均为 24 小时。托管内容的有效期最长为 7 天。

Context Capsule + ProofSlip

这两款产品彼此独立，并通过可选引用关联：

• Context Capsule 用于导航：“当前情况如何、哪些内容重要，以及接下来应该做什么？”
• ProofSlip 用于提供证据：“发布环境证明了什么，下一位 Agent 能否检查这些内容？”

只有在交接声明有相关独立证据时，才将 ProofSlip ID 填入 references.proofslip_ids。下一位 Agent 仍需获取并检查证明；仅有 ID 并不能让声明得到验证。

可选托管分享

现有的 Hono/Postgres API 仍可使用，适用于你明确需要为另一台机器或其他人提供短期交接 URL 的场景。它是可选的传输方式，并非默认的编写体验。

获取 API 密钥

curl -X POST https://www.contextcapsule.ai/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

API 密钥以 ak_ 开头。

创建托管胶囊

curl -X POST https://www.contextcapsule.ai/v1/capsules \
  -H "Authorization: Bearer ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "summary":"Refresh-token migration implemented; staging is not verified",
    "decisions":["Keep the legacy endpoint for three consumers"],
    "next_steps":["Run the staging smoke test","Ask before release"],
    "payload":{"schema_version":"coding-handoff/v1"},
    "refs":{"receipt_ids":[]},
    "expires_in":86400,
    "idempotency_key":"refresh-handoff-81d9c1a",
    "audience":"human"
  }'

响应字段包括 capsule_id、capsule_url、summary、decisions、next_steps、created_at、expires_at 和 idempotency_key。

获取

curl "https://www.contextcapsule.ai/v1/capsules/cap_...?format=json"

获取内容无需身份验证。任何拥有 ID 或 URL 的人都可以在胶囊过期前读取它。

完整托管接口规范：API 文档 · OpenAPI · llms-full.txt

可选 MCP 传输

npx -y @contextcapsule/mcp-server

MCP 服务通过托管 API 提供 create_capsule、fetch_capsule 和 signup。创建需要 CONTEXTCAPSULE_API_KEY；获取是公开的。对于本地编码交接，建议优先使用 Agent Skill，因为它可以检查代码库的新鲜度，且无需上传内容。

自托管

要求：Node.js 18+ 和 PostgreSQL。

git clone https://github.com/Johnny-Z13/context-capsule.git
cd context-capsule
npm install
cp .env.example .env
npm run db:migrate
npm run db:seed -- [email protected]
npm run dev

环境变量：

变量	必需	用途
DATABASE_URL	是	PostgreSQL 连接字符串
BASE_URL	是	胶囊链接的公开基础 URL
CRON_SECRET	生产环境	保护过期清理操作
RESEND_API_KEY	网页注册	为 source: web 发送 API 密钥
DEV_SECRET	可选	保护本地开发者控制台
NODEJS_HELPERS	Vercel	部署运行时设为 0

开发

npm run dev
npm test -- --run --configLoader runner
npx tsc --noEmit

针对 Skill 的测试：

npx vitest run tests/skills/contextcapsule-handoff.test.ts --configLoader runner

HTTP API 有意保持与原始扁平 summary、decisions、next_steps、payload 和 refs 架构向后兼容，而本地 Skill 则提供更丰富的编写和新鲜度规范。

许可证

MIT