ccpkg (Zircote)

ccpkg

](https://ccpkg.dev/spec/specification.html)    ](https://github.com/zircote/ccpkg/discussions)

AI编码辅助扩展的开放式打包格式。

ccpkg是一种自包含的归档格式，用于将技能、代理、命令、钩子、MCP服务器和LSP服务器打包和分发为单个便携式单元。一个文件，一个安装，零安装后步骤。

问题

AI编码助手的可扩展性越来越强，但共享扩展是分散的：

• 脆性 --当作者推送更改时，从Git存储库安装的扩展会自动中断。没有版本固定，没有完整性验证，没有依赖性出售。
• 启动缓慢 --每次会话启动都会从远程存储库获取插件状态。多个插件意味着在助手准备就绪之前需要几分钟的延迟。
• 没有信任信号 --找到好的扩展意味着口碑。没有管理，没有验证，没有结构化元数据可供过滤。
• 配置负担 --MCP服务器配置最终隐藏在插件缓存目录中。机密、环境变量和身份验证令牌需要编辑不透明文件。

解决方案

A. .ccpkg 文件是一个标准的ZIP存档，其中包含一个声明性 manifest.json 以及所有扩展组件。安装是确定性的：提取、配置、注册。没有安装后脚本，没有网络获取，没有构建步骤。

example-plugin-1.0.0.ccpkg (ZIP)
├── manifest.json           # Package identity, components, config
├── skills/                 # SKILL.md files (Agent Skills format)
├── agents/                 # AGENT.md files
├── commands/               # Slash command definitions
├── hooks/                  # Event handlers (hooks.json + scripts)
├── mcp/                    # MCP server config template
├── lsp/                    # LSP server config template
├── instructions/           # INSTRUCTIONS.md + tool-specific mappings
└── LICENSE

主要特点

• 独立档案 --所有依赖项都在内部提供。没有运行时网络获取。
• 跨工具可移植性 --适用于Claude Code、Gemini CLI、Codex、Copilot和其他兼容工具。基于通用标准（MCP、LSP、代理技能）构建。
• 延迟加载 --仅在启动时加载元数据。按需加载完整内容。20个已安装的软件包的启动时间为零。
• 类型化配置 --Manifest声明了配置槽（秘密、字符串、枚举、路径）。用户在安装时配置一次。自动将接线值模板化到MCP/LSP配置中。
• 确定性锁文件 -- ccpkg-lock.json 用校验和固定精确版本。承诺在团队中共享相同的环境。
• 去中心化注册中心 --无需中央权威机构。注册表是可托管在GitHub Pages、S3或任何静态服务器上的JSON文件。
• 安装范围控制 --用户标志总是赢。全局安装(~/.claude/packages/)或每个项目(`

/.claude/packages/`).

• 开发模式 --Symlink本地目录，无需重新打包即可进行实时开发。

建立在开放标准之上

文档

清单示例

{
  "spec_version": "2026-02-14",
  "name": "api-testing",
  "version": "1.0.0",
  "description": "Skills and tools for API testing workflows.",
  "author": {
    "name": "Example Org",
    "url": "https://github.com/example-org"
  },
  "license": "MIT",
  "scope": "project",
  "components": {
    "skills": ["skills/openapi-validator", "skills/request-generator"],
    "commands": ["commands/run-tests.md"],
    "hooks": "hooks/hooks.json",
    "mcp": "mcp/.mcp.json",
    "instructions": "instructions/INSTRUCTIONS.md"
  },
  "config": {
    "API_BASE_URL": {
      "type": "string",
      "description": "Base URL for the target API.",
      "required": true
    },
    "API_KEY": {
      "type": "secret",
      "description": "Authentication key for the target API.",
      "required": true
    }
  },
  "targets": {
    "claude": { "instructions_file": "CLAUDE.md" },
    "codex": { "instructions_file": "AGENTS.md" }
  }
}

状态

本规范是 草案 （2026-02-14版）。该格式对于实验和反馈来说足够稳定，但在1.0之前可能会发生变化。

贡献

欢迎反馈和贡献：

• 打开一个问题 用于错误报告、问题或功能请求
• 提交拉取请求 用于规范改进或更正
• 加入讨论

引用此项目

如果您在学术或技术写作中引用ccpkg，请使用 GitHub的 “引用此存储库” 按钮或下面的BibTeX条目 （生成自 CITATION.cff):

@software{allen_ccpkg_2026,
  author       = {Allen, Robert},
  title        = {ccpkg},
  version      = {0.0.4},
  date         = {2026-02-22},
  url          = {https://ccpkg.dev},
  license      = {CC-BY-4.0}
}

致谢

ccpkg基于以下开放标准构建：

模型上下文协议。 *模型上下文协议规范。*

微软。 *语言服务器协议。*

代理技能。 *代理技能格式。*

许可证

本规范发布于 CC-BY-4.0.