AI coding agent 用得多了，项目里会慢慢多出 prompt 之外的东西。
你可能会有约束代码风格的 rule、处理固定任务的 skill、描述产品边界的 spec、连接外部服务的 MCP 配置，以及记录历史决策的 memory。它们有些来自开源社区，有些属于团队共享资产，还有一些只对当前项目成立。
刚开始把它们随手放在项目里，通常也不会马上出问题。等项目变大、换了 agent，或者隔几个月回来继续做时，麻烦就来了：哪些文件要提交到 Git？外部资源有没有更新？一条规则适用于整个团队，还是只适用于当前仓库？
AI 工作流变复杂，很多时候是因为资源没有边界。
Bear. CTXPM 就是从这个问题出发的。CTXPM 是 Context Package Manager 的缩写，是一套开源的 AI 资源管理协议，也提供配套的 ctxpm CLI。它把 AI 使用的上下文和能力，按项目资源的方式整理起来。
不同于传统的包管理工具需要开发者手动敲入各种命令来安装、更新、校验，CTXPM 采用 AI 驱动优先的设计。协议规则和操作逻辑通过 agent 入口文档注入，配合内置 skill 和 CLI 工具，让 AI agent 能在日常编码、review、调试等任务间隙，自主完成资源的检查、升级、校验和整理流程。你不需要记住每个子命令的参数，AI 会在需要时读取协议、调用工具、向你确认决策。
先把它当成一套项目协议
Bear. CTXPM 不要求你改写现有的 skill、rule 或 prompt，也不要求项目绑定某个 agent。它先约定几件实际工作中绕不开的事：
- 项目有哪些 AI 资源？
- 它们来自外部，还是由项目自己维护？
- 资源应该存放在哪里，是否进入版本控制？
- 不同 AI agent 应该从哪个入口读取它们？
- 如何安装、校验、迁移和更新这些资源？
这套约定落在三个地方：ctxpm.yaml 清单、.ctxpm/ 目录结构，以及项目根目录中的 agent 入口文档。CLI 负责把安装、检测和校验做得稳定一些，协议本身不依赖 CLI。即使当前环境跑不了工具，AI 也能根据清单和目录理解项目。
两种语义，划清资源边界
Bear. CTXPM 只用两种归属语义：dependency 和 package。
dependency 是项目使用的外部 AI 资源。来源可以是 Git 仓库、OCI registry、文件路径或其他地方。完整内容通常不提交进当前项目，但 ctxpm.yaml 会记录它的来源、路径和稳定版本，使用方式很像代码项目中的第三方依赖。
package 是当前项目自己维护的 AI 资源。它和项目的业务、代码结构或协作方式有关，应该和源码一起提交、review，跟着项目一起修改。
资源归属和资源类型是两回事。无论是 dependency 还是 package，资源都可以属于下面这些类型：
skillrulespecpromptmemorymcp
例如，从 GitHub 引入的代码提交 skill 是 dependency + skill。只适用于当前仓库的发布流程是 package + skill，项目自己的源码编辑边界则可以是 package + rule。
这样一来，资源由谁维护、出了问题找谁改，就不会再混在一起。
一个真实的目录是什么样
采用 Bear. CTXPM 的项目，常见结构大致如下：
ctxpm.yaml 是项目的资源清单。安装后的外部资源放在 .ctxpm/dependencies/，通常加入 .gitignore；项目自己的资源放在 .ctxpm/packages/，通常进入版本控制。
.ctxpm/AGENTS.md 是共享的 agent 入口源文件。项目可以按启用的 agent profile，在根目录生成 AGENTS.md、CLAUDE.md、GEMINI.md 等兼容入口，并让它们指向同一份内容。规则只维护一份，入口文件各自照顾不同 agent 的习惯。
入口文档还会告诉 AI 怎么发现资源。先读项目清单，再看项目自己的 packages，然后才看外部 dependencies。只有任务需要历史背景时，才加载对应的 memory，上下文不会一开始就被所有文件占满。
这是 AI 驱动的关键： 协议不是静态配置，而是 AI 的操作指南。AI 会按优先级读取资源、判断哪些规则适用于当前任务、在合适时机执行资源检查和维护操作，开发者不需要在编码中途打断来手动执行这些流程。
这个仓库怎么使用 CTXPM
Bear. CTXPM 仓库本身就按这套规则组织。ctxpm 的管理能力和第三方 git-commit skill 属于外部 dependency。只服务于这个仓库的发布流程属于 package + skill；提醒产品源码不要和仓库自身受管资源混在一起的约束，则是 package + rule。
对应的清单可以简化为：
version: 1.0
project:
name: Bear.CTXPM
agents:
- generic
- claude-code
dependencies:
- name: ctxpm
type: skill
path: .ctxpm/dependencies/skills/ctxpm
source:
type: git
url: https://github.com/gBearBest/Bear.CTXPM
packages:
- name: ctxpm-release
type: skill
path: .ctxpm/packages/skills/ctxpm-release
- name: ctxpm-source-boundary
type: rule
path: .ctxpm/packages/rules/ctxpm-source-boundary.md
清单的作用是把责任写下来。后续进入仓库的 AI 能知道哪些内容跟着上游更新，哪些内容由当前项目负责，以及修改源码前要先读哪些规则。
从一次性安装，变成 AI 自主维护的流程
传统包管理器需要你记住命令、查文档、手动触发检查。CTXPM 把这些步骤变成 AI 可以理解和执行的协议：
这些命令你可以自己运行，也可以交给 AI。项目采用 CTXPM 协议后，AI agent 会在处理常规任务时：
- 发现项目里未受管的 AI 资源，询问是否需要迁移。
- 在适当时机检查外部依赖是否有更新。
- 验证清单与实际目录是否一致，自动修复入口 symlink。
- 遇到资源冲突或归属不明时，向你确认处理方式。
AI 不是简单地执行固定脚本，而是理解协议的语义边界，根据项目状态判断应该做什么、什么时候做、是否需要确认。
detect 与 migrate 用来处理历史遗留资源：先只读扫描，再由用户确认哪些内容应该迁移。check-updates 与 update 也被刻意拆开：先发现变化并报告，再在确认后执行更新。
对于普通外部 Git 资源，Bear. CTXPM 记录资源所在路径最后一次发生变化的 commit，不一定使用整个仓库最新的 HEAD。大型仓库只改了其他目录时，所依赖的 skill 不会因此出现一次虚假的升级。版本号对应的是实际安装的资源根目录。
协议优先，AI 理解边界，工具负责重复劳动
Bear. CTXPM 先定义协议，是因为项目不能依赖某个二进制工具才能让 AI 理解工作环境。协议通过入口文档注入给 AI，让 AI 知道：
- 资源存放在哪里，哪些受管、哪些散落。
- 外部依赖的边界在哪，什么时候该检查更新。
- 修改前应该读哪些规则，修改后需要同步哪些清单。
- 遇到归属不明的资源，应该询问还是忽略。
创建目录、修复入口 symlink、安装依赖、计算版本、检查未受管资源、验证清单，这些固定步骤交给 CLI 更合适。资源归属怎么判断、风险怎么解释、是否请求确认，以及迁移冲突怎么处理，则留给 AI。
协议把规则说清楚，CLI 把固定步骤做稳定，AI 理解语义边界并处理需要判断的部分。这样一来，开发者可以专注在决策层面，而不是记忆和重复执行固定命令。
AI 能做什么，你做什么
采用 CTXPM 后，资源管理的日常工作主要由 AI 完成：
AI 会自主执行：
- 扫描项目，发现未受管的 AI 资源。
- 读取
ctxpm.yaml，理解资源归属和依赖关系。 - 在合适时机检查外部依赖是否有更新。
- 修复入口 symlink，保持目录结构一致。
- 按优先级加载资源，避免上下文浪费。
你只需要做决策：
- 散落的资源是迁移到
packages，还是标记为dependency？ - 外部依赖有新版本，是否升级？
- 规则冲突时，保留哪一份？
这和传统工具的体验完全不同。npm install 需要你记住命令、查看文档、手动触发。CTXPM 的 AI agent 会在你编码、review、调试时，在后台检查项目状态，发现问题后主动询问你的决策。
谁适合使用 CTXPM
一次性的 AI demo 可能用不上 CTXPM。项目开始长期维护后，下面这些情况很常见：
- 多个 agent 需要读取同一套项目规则。
- 团队希望复用共享 skill，又不想把它复制进每个仓库。
- 项目自己的 prompt、spec 和 memory 需要和源码一起 review。
- 外部资源需要知道来源、版本和更新边界。
- 历史上已经有散落的 AI 文件，需要先盘点再迁移。
CTXPM 不替你写 prompt，也不决定哪个 agent 更聪明。它把资源的归属、位置和生命周期写清楚，让 AI 工作流可以跟着项目一起维护。
如何开始
接入 CTXPM 不需要先学命令。把下面这句话交给正在使用的 AI agent：
请按照 https://raw.githubusercontent.com/gBearBest/Bear.CTXPM/latest/INSTALL.md 文档中的说明，对本项目进行检测、安装、初始化与改造，使其成为用于管理 AI 依赖与 AI 资源的 Bear.CTXPM 协议结构。
AI 会先识别项目正在使用的 agent 和已有资源，再准备项目本地 CLI、初始化目录与清单。遇到资源归属或迁移问题时，它会先停下来向你确认。
从这一步开始，CTXPM 的维护流程就切换到 AI 驱动模式。之后你在项目中日常工作时，AI 会在后台：
- 发现散落的资源，询问是否纳入管理。
- 检查外部依赖更新，报告变化并等待确认。
- 修复入口 symlink，保持项目结构一致。
- 读取协议规则，决定何时加载哪些资源。
如果项目里已经积累了规则、skill、prompt 或 memory，早点把边界理清，后面会省很多整理工作。Bear. CTXPM 关注的就是这一步：让已经存在的上下文有地方放，也知道该由谁维护。而整个流程中，你只需要做决策，其他步骤交给 AI 和工具。