💡阅读指南

当前 Plan 负责设计胶囊系统的运行结构、开发产物和基座兼容性，不负责安装包。安装形式、环境检查、升级和卸载都属于后续发布阶段。这里需要把两个阶段分开，避免安装问题过早干扰核心功能，也避免开发完成以后才发现业务代码已经绑定某个 Agent 基座。

4.1 开发和发布是两个阶段

开发阶段要回答的是系统怎样工作。胶囊系统由 Agent 基座、Skill、CLI、Python 模块和飞书共同组成，当前 Plan 需要确定这些部分怎样配合，代码怎样测试，以及如何避免依赖 Codex 或 Hermes 的内部实现。

发布阶段处理的是另一组问题：用户拿到什么文件，怎样安装 Skill 和 CLI，环境不满足条件时如何提示，以及以后怎样升级或卸载。这些问题当然重要，但它们不会改变胶囊系统怎样理解资料、生成证据和维护知识页，没有必要混进当前功能 Plan。

两个阶段仍然需要留下清楚的边界：

阶段 需要处理的内容
当前 Plan 与开发 设计并实现 Skill、CLI、Python 和飞书之间的关系，完成测试，保证业务核心与 Agent 基座无关
后续发布与打包 决定安装包形式、安装位置、环境检查、配置引导、升级、卸载和发布验收

Spec Kit 并没有强制规定一个独立的发布阶段。胶囊系统主动把它拆出去，是因为安装包本身也需要单独选择形式和处理失败情况。等核心功能开发并验收完成以后，可以再为发布工作建立新的技术简报和 Plan；如果安装过程还要通过 Agent 与用户交互，也可以进一步设计独立的安装 Skill。

4.2 Codex 开发与 Hermes 兼容性测试

胶囊系统还有一个与传统项目不同的问题：我们在 Codex 中开发，教材还要用 Hermes 验证兼容性。开发阶段不能每改一行代码，就先制作一次正式安装包。这个问题很像开发 Web 应用时使用本地服务器，只是 SE 项目的开发环境不是一台临时 Web 服务器，而是另一个可以读取 Skill、调用工具的 Agent 基座。

Codex 不只是修改代码的工具，它本身也能充当胶囊系统的运行时 Agent。只要 Codex 读取同一份 Skill，调用同一个 capsule CLI，并按照相同契约处理返回结果，就可以在开发阶段完整执行胶囊系统。Hermes 是本教材选择的兼容性测试环境，但不是 SE 产品的业务核心。

因此，Codex 和 Hermes 不需要直接调用对方。两者连接的是同一组开发产物：

Text
Codex 修改源码并充当开发态 Agent
                ↓
       读取仓库中的源码 Skill
                ↓
       调用本地 uv 环境中的 CLI
                ↓
          写入飞书测试空间

同一套 Skill + CLI 契约
                ↓
       Hermes 基座兼容性验证

开发时，Codex 可以直接读取仓库中的 Skill，并调用当前项目环境中的 CLI。这样，Python、Skill 和 Agent 编排都能在一个环境中反复修改和验证，不必每次切换到 Hermes。这个阶段使用专门的飞书测试空间，避免测试数据进入用户的正式知识库。

这里真正稳定的连接点，是 Skill 表达的工作方法和 CLI 的输入输出契约。Codex 和 Hermes 不需要采用完全相同的模型，也不需要产生一字不差的推理过程。只要两种基座都能理解 Skill，并且 CLI 的参数、返回字段、错误状态和后续动作保持明确，胶囊系统的业务核心就不必跟着基座变化。

但是，基座无关不等于完全不需要适配。不同 Agent 发现 Skill、调用终端、读取图片和管理权限的方式可能不同。项目需要把这些差异限制在很薄的适配层中，不能让 Python 业务模块直接依赖 Hermes 或 Codex 的内部实现。两种开发测试环境使用的是同一套核心：

Codex 开发环境 Hermes 兼容性测试环境
Codex 直接读取仓库中的源码 Skill Hermes 读取仓库中的同一份源码 Skill
CLI 在本地 uv 开发环境中运行 CLI 同样从当前项目开发环境中运行
可以验证 Python、CLI 和完整 Agent 编排 重点验证 Skill 发现、工具调用和基座兼容性
使用飞书测试空间和测试配置 使用同一套飞书测试空间和隔离配置

因此，开发阶段的测试也需要分层。Python 函数和 CLI 契约由 Codex 执行自动化测试，涉及语义理解的完整流程也可以直接由 Codex 根据 Skill 操作。等这些测试通过以后，再到 Hermes 中检查基座差异，最后在飞书测试空间完成端到端验收：

Text
单元测试
   ↓
CLI 契约测试
   ↓
Codex 加载 Skill，完成 Agent 流程测试
   ↓
Hermes 兼容性冒烟测试
   ↓
Hermes + 飞书测试空间端到端验收

这种安排不是让 Codex 模拟 Hermes，而是承认两者都可以充当 SE 产品的 Agent 基座。Codex 完成大部分开发验证；Hermes 检查自身的 Skill 加载、工具权限、多模态输入和对话行为。以后如果换成另一个 Agent 基座，也应该沿用同样的方法：复用 Skill、CLI 和 Python 核心，只增加必要的兼容性验证。

4.3 本次开发需要留下的产物

当前开发不能只留下一组 Python 函数。Agent 还需要读取 Skill，通过稳定的 CLI 调用 Python，开发者也需要能够重复执行测试。因此，本次开发应形成下面的项目结构：

Text
capsule-system/
├── skills/capsule-system/    Agent 基座使用的 Skill
├── src/capsule_system/       Python 包和 capsule CLI
├── tests/                    自动化测试和验收资料
├── pyproject.toml            项目与依赖定义
├── uv.lock                   锁定依赖版本
└── README.md                 开发运行与测试说明

这里列出的是开发产物，不是安装包。skills/ 和 src/ 属于产品源码，tests/ 及其中经过标注的资料属于开发验证资产。它们会保留在项目仓库中，但以后制作用户安装内容时，没有必要把测试资料一起放进去。

4.4 安装包留到发布阶段

功能开发完成以后，发布阶段再决定用户最终拿到什么。那时可以选择 Python Wheel、压缩包或安装脚本，也可以增加一个安装 Skill，引导用户检查环境并调用确定性的安装工具。这些方案涉及目标操作系统、Agent 的 Skill 目录和权限确认，现在还没有必要提前确定。

环境检查也放在这个阶段。开发测试可以直接检查 Python、CLI、Skill 和飞书是否可用，但面向用户的检查命令需要考虑怎样解释错误、怎样取得修改环境的授权，以及失败以后如何退出。它已经超出当前功能 Plan 的范围。

4.5 Brief 只记录当前技术边界

当前 Planning Brief 只需要记录产品怎样开发和验证：Agent 基座是主控，Skill 通过稳定 CLI 调用 Python，业务核心不依赖 Codex 或 Hermes，测试使用独立的飞书空间。同时还要明确，本次不设计安装包、安装 Skill、用户环境检查、升级和卸载。

这样处理以后，当前 Plan 不会被发布细节拖住，开发出来的核心又不会绑定某台电脑或某个 Agent 基座。等功能通过验收，再使用单独的发布 Plan 解决安装问题。