capsule

---

MCP 为 Agent 提供工具。技能为 Agent 提供操作流程。Capsule 为 Agent 提供精简的项目上下文。

大型代码仓库会让编码 Agent 不断花费 token，反复重新发现相同的文件、决策、约定和设置详情。Capsule 的目标是将大型、多会话 Agent 工作中重复的代码仓库探索上下文减少 50–70%。

安装

无需安装——使用 npx 直接运行（始终获取最新版本）：

npx capsulectx init

或者使用包管理器全局安装：

# npm
npm install -g capsulectx

# pnpm
pnpm add -g capsulectx

# yarn
yarn global add capsulectx

# bun
bun add -g capsulectx

保持更新：

npm install -g capsulectx --prefer-online

提示： npx 是最简单的方式——它始终运行最新发布的版本，无需手动更新。

快速入门

npx capsulectx init

Capsule 会扫描代码仓库，可选择使用 AI 丰富 Capsule 内容（通过已安装的 Claude CLI、API 密钥，或为任何基于浏览器的 AI 生成提示词），并创建：

.capsules/
  index.md
  architecture.md
  setup.md
  api.md
  data.md
  ui.md
  testing.md
  deployment.md

每个 Capsule 都是一个 Markdown 文件，包含 JSON frontmatter 格式的源文件指纹：

---json
{
  "name": "api",
  "sources": ["src/api/**"],
  "fingerprints": { "src/api/users.ts": "sha256:..." },
  "updated_at": "2026-06-20T14:00:00.000Z"
}
---

# API Capsule

## Purpose

Request handlers, routes, controllers, and service boundaries.

## Key Files

- `src/api/users.ts`: source file matched by this capsule.

## Decisions

- Record stable decisions here so future agents do not rediscover them.

Agent 会读取 .capsules/index.md，选择相关的 Capsule，检查其是否过时，然后只检查真正相关的源文件。

命令

命令	功能
capsule init	扫描代码仓库，运行 AI 内容丰富（可选），写入所有 Capsule
capsule enrich	对现有 Capsule 重新运行 AI 内容丰富
capsule apply	将 AI 生成的 JSON 应用到 Capsule 的约定和决策中
capsule write <name>	根据源文件刷新一个 Capsule（保留你的编辑）
capsule refresh <name>	明确刷新一个 Capsule
capsule refresh --all	明确刷新所有检测到的 Capsule
capsule get <name>	将一个 Capsule 输出到标准输出
capsule scan	输出检测到的源文件组，但不写入文件
capsule stale [name]	检查自上次写入后哪些源文件发生了变化
capsule estimate <name>	显示一个 Capsule 预计节省的 token 数
capsule stats	显示所有 Capsule 节省的 token 数
capsule report [name]	显示可复现的源文件、Capsule 和过时内容的 token 节省情况
capsule report --write	将 .capsules/report.md 写入为证明材料
capsule check	适用于 CI 的新鲜度和配置检查；如果 Capsule 过时或缺失，则以非零状态码退出
capsule --mcp	启动 MCP 服务，以便与 Agent 原生集成

MCP 服务

Capsule 提供 MCP 服务，让 Claude Code 和其他兼容 MCP 的 Agent 能够原生发现并使用 capsules——无需手动读取文件。

添加到项目的 .claude/settings.json：

{
  "mcpServers": {
    "capsule": {
      "command": "npx",
      "args": ["capsulectx", "--mcp"]
    }
  }
}

或者添加到全局的 ~/.claude/settings.json，以便在所有项目中启用。

配置完成后，Agent 会自动获得以下工具：

工具	功能
capsule_list	列出所有 capsule 及其新鲜度状态
capsule_get	读取 capsule 的压缩上下文；过时时会发出警告，但不会写入
capsule_refresh	显式刷新一个或所有 capsule
capsule_stale	检查哪些 capsule 的来源已过时
capsule_stats	显示每个 capsule 节省的 token 数量
capsule_report	显示机器可读的发现节省情况证明
capsule_check	检查过时、缺失或配置问题，适用于 CI
capsule_init	为当前仓库生成 capsules

Capsules 也可作为 MCP 资源通过 capsule:///index 和 capsule:///{name} 获取。

查看节省情况

$ capsule report architecture

Capsule: architecture

  capsule       status     source   capsule     stale   saved
  architecture  fresh       9,607       417         0     96%

Token 数量使用 cl100k_base 分词器进行精确测量。

对于 CI，请运行：

npx capsulectx check

如果 capsules 已过时、缺失或因配置无效而受阻，命令将以非零状态码退出。

Agent 工作流

将以下内容添加到 AGENTS.md、CLAUDE.md、Cursor 规则或 Agent 指令中：

Before working in this repo:

1. Read `.capsules/index.md` if it exists.
2. Read the capsule matching the task area.
3. Run `capsule stale <name>` when the CLI is available.
4. If stale, inspect changed source files before editing.
5. Update capsules when durable project knowledge changes.

适用于任何能够读取文件的 Agent——Claude Code、Codex、Cursor、Windsurf、Devin，以及自定义 MCP Agent。

自定义分组

Capsule 开箱即用地检测标准目录结构。对于非标准结构，请添加 .capsules/config.json：

{
  "groups": [
    {
      "name": "workers",
      "description": "Background jobs, queues, and scheduled tasks.",
      "sources": ["src/workers/**", "src/jobs/**"]
    }
  ],
  "ignore": ["legacy/**"]
}

与默认分组同名的 groups 条目会覆盖该分组。新名称会追加到末尾。ignore 模式会扩展默认忽略列表。

有关公开的 capsule 文件格式，请参阅 docs/capsule-format.md。

构建演示

此 README 中的动画是生成的 GIF——无需屏幕录制工具。

npm run demo

需要 rsvg-convert（librsvg / librsvg2-tools）和 ffmpeg。该脚本会根据以 2× 分辨率渲染的 SVG 帧生成 docs/demo.gif，适用于视网膜屏幕。请参阅 scripts/build-demo.mjs。

文档站点

开源文档位于 docs-site/，使用 VitePress 构建。

npm run docs:dev
npm run docs:build

状态

Capsule 尚处于早期阶段，但已可用。当前功能包括：

• 与语言无关的仓库扫描，支持 monorepo（Turborepo、pnpm workspaces）
• 静态分析：框架检测、表/模型提取、路由检测、环境变量
• 初始化时进行 AI 增强——启动已安装的 Claude CLI、调用 Claude/OpenAI API，或为任何基于浏览器的 AI（Claude.ai、ChatGPT、Cursor、Windsurf）生成提示词
• 安全写入式重新生成：刷新时保留人工对约定和决策的编辑
• 用于原生 Claude Code / Agent 集成的 MCP 服务
• 实际 token 计数（cl100k_base）及节省情况面板
• TypeScript API 接口提取
• 二进制文件过滤
• 过时检测和 token 节省估算
• 可复现的 report 和适用于 CI 的 check
• 通过 .capsules/config.json 自定义分组配置
• 自动将 capsule 指令补丁写入 CLAUDE.md、AGENTS.md、.cursorrules、.windsurfrules

路线图：

• 更智能的 write，能够比较源文件变更并建议有针对性的更新
• 真实 Agent 会话的前后 token 报告
• 用于 capsule check 的 GitHub Action 封装

本地开发安装

git clone https://github.com/dawitlabs/capsule.git
cd capsule
npm install
npm run build
node dist/cli.js init

许可证

MIT