胶囊系统的 Planning BriefHERMES & AGENT ENGINEERING · 课时 05

# 胶囊系统 Planning Brief

> 本 Brief 是胶囊系统自定义的 Plan 输入文档，不属于 Spec Kit 标准文件。

## 规划范围

- Plan 覆盖完整的 `spec.md`。
- P1 和 P2 统一规划，并在同一次实现中完成。
- 本次开发一个由 Agent 基座驱动的 SE 项目，不建设独立应用或 Web 服务。
- 本 Plan 只规划产品源码、开发测试和基座兼容性，不规划安装包与发布流程。

## 已确定的产品形态

- 胶囊系统是一个由通用 Agent 基座驱动的 SE 项目。用户通过 Agent 对话提交资料、查询结果并作出决定。
- 当前 Agent 基座是运行时主控。它负责理解用户意图，并根据 Skill、当前上下文和工具返回结果决定下一步。
- SE 产品的业务核心不得依赖 Hermes 或 Codex 的内部实现。Codex 是开发与主要测试环境，Hermes 是当前选择的兼容性测试环境；更换兼容 Agent 基座时，应复用 Skill、CLI 和 Python 核心，只替换必要的加载与工具适配。
- Skill 是 Agent 操作胶囊系统时使用的工作方法，记录意图与命令的对应关系、信息不足时的询问方式、工具结果的处理规则和人工审核格式。
- 第一版不建设 FastAPI 服务、HTML 页面或独立前端，人工审核也通过 Agent 对话完成。
- 使用飞书保存并展示长期数据，包括知识页、衍生证据及其索引、处理记录和审核队列。可以把飞书理解成传统的数据库作用。
- 技术方案必须遵守项目宪章。
- Plan 不得擅自删减 SPEC 的需求，也不得在没有说明影响时引入额外平台。

## 已确定的运行结构

- 当前 Agent 根据 Skill 调用胶囊系统提供的稳定 CLI，CLI 再将命令分派给内部 Python 模块和函数。
- Python 不负责从头到尾主控完整流程，也不主动调用当前 Agent 会话。每次 CLI 调用只完成一项边界明确的操作，然后向 Agent 返回机器可读的结果。
- CLI 返回值至少应表达本次调用的执行结果、结果引用、错误信息和当前允许的后续动作。确切字段由 Plan 设计。
- Skill 负责说明何时调用哪个能力、怎样把用户输入整理成结构化参数、如何根据 Python 返回的 `next_action` 继续下一步、何时追问用户，以及怎样展示结果。Skill 不直接保存业务状态，也不承载不可逆操作、状态迁移等需要稳定执行的业务规则。
- 第一版不让 Python 绕过当前 Agent 直接调用另一套通用大模型 API。需要理解图片、判断主题关系、比较新旧知识或组织知识页时，Python 可以在当前执行中返回结构化 `next_action`；Agent 按 Skill 完成该语义任务，再把符合指定 Schema 的结果提交给 Python。`next_action` 只存在于本次执行，不保存为可以恢复的检查点。
- 一次完整流程可以包含 Agent 与 Python 的多次往返：用户发送自然语言 → Agent 判断意图 → Skill 调用 CLI → Python 完成当前确定性步骤并返回 `next_action` → Agent 完成语义任务 → Skill 把结构化结果交回 CLI → Python 校验并继续。所有往返必须在同一次任务中完成，最后只能以成功、生成审核项或失败结束。
- Agent 负责自然语言和语义理解；Python 负责输入校验、策略约束、不可逆操作和最终写入。模型产生的结构化理解结果必须先经过 Python 校验，才能改变证据或知识页。
- 第一版不管理断点和中间状态。任务执行期间的数据只保存在当前会话、内存或受控临时目录中；成功以后才保存最终结果，失败或会话中断时清理临时数据，用户需要重新发起任务。
- 需要人工判断时，当前任务以生成审核项作为最终结果结束，不保存恢复位置。用户作出决定以后，由 Agent 启动一项新的处理任务。

## 确定性操作与语义理解的边界

- 文件校验、PDF 文字提取、哈希计算、状态校验和飞书写入等可以重复执行并自动测试的操作，由 Python 完成。
- 通用语言理解和视觉理解由当前 Agent 基座完成，包括理解用户意图、判断独立图片表达的知识、比较新旧观点和组织知识页内容。
- Python 不再单独接入另一套通用大模型 API，以免同一次运行中产生两套模型配置、上下文和错误处理方式。
- 音频转写等目标单一、输入输出边界固定的专用模型可以由 Python 调用。Plan 需要把这类模型当成确定性工具进行封装和测试。
- Agent 无法可靠判断，并且继续执行会影响重要结果的问题，统一进入人工审核。

## 本次开发与兼容要求

- Codex 直接读取仓库中的源码 Skill，并调用本地 `uv` 开发环境中的 CLI，完成主要开发测试。
- Hermes 在测试环境中读取同一份源码 Skill 和 CLI，完成基座兼容性冒烟测试与端到端验收。
- Plan 需要把基座差异限制在 Skill 加载、工具调用、多模态输入和权限配置等适配边界中，Python 业务核心不得导入 Hermes 或 Codex 的内部模块。
- 确定性的 Python 行为和 CLI 契约由 Codex 执行自动化测试；Codex 还要读取 Skill，完成开发态 Agent 流程测试。
- 开发阶段使用独立的飞书测试空间和测试配置，不能把测试数据写入用户的正式知识库。
- 测试代码和经过标注的验收资料集属于开发验证资产，保存在项目仓库中，不属于以后交给用户安装的运行产品。
- 本 Plan 不设计安装包、安装 Skill、用户环境检查、升级或卸载流程。这些内容等功能开发和验收完成后，进入单独的发布与打包阶段。

## 初步技术建议

- Python 以 3.12 为起点，使用 `pyproject.toml` 和 `uv` 管理环境与依赖；Phase 0 需要再核对 Codex、Hermes 及飞书 CLI 的兼容性。
- 第一版采用模块化单体结构，不拆分微服务。资料接收、证据生成、知识演化、审核队列和飞书访问仍分成独立模块。
- 建议用 Pydantic 定义 CLI 的输入、输出和最终结果对象，避免不同 Agent 基座与 Python 对同一字段作出不同理解。
- 优先使用已安装的飞书 CLI。如果 Phase 0 发现必要能力没有覆盖，应记录缺口并重新确认 Plan，不能在实现阶段静默加入 OpenAPI 或官方 SDK 作为第二套调用方式。
- 使用 `pytest` 编写单元测试和端到端验收测试。

## 审核队列的交互规则

- 审核队列是一组等待用户决定的持久化记录，不是页面或独立子系统。
- 用户让当前 Agent 查看审核队列时，Agent 按统一格式列出审核项的编号、类型、中断位置、触发原因、已有依据、受影响的知识页、可选决定、各选择的后果和系统建议。
- 用户在对话中补充信息或选择处理方式。Agent 把自然语言决定转换成结构化指令；不可逆操作必须再次确认明确对象。
- 需要人工判断时，原任务以生成审核项作为最终结果结束，不保留等待恢复的执行现场。
- 用户作出决定后，Agent 启动一项新的处理任务；Python 校验并执行决定，并把决定和最终结果写入飞书。

## 交给 Phase 0 的开放问题

- 飞书知识库与文档如何承载主题页和概念页？多维表格如何承载证据索引、最终处理记录、审核项和审核记录？
- 长文形式的衍生证据应保存在飞书文档中，还是拆分后保存在多维表格中？
- 稳定 CLI 应该提供哪些命令？命令的输入、输出、错误码、结果引用和允许的后续动作应采用什么结构？
- Codex 和 Hermes 在开发测试中分别怎样读取同一份 Skill、调用同一个 CLI，以及工具输入、输出和错误应采用什么结构？
- 音频转写、PDF 文字提取、网页正文抽取分别使用哪些 Python 工具，以及它们如何在处理结束后及时释放临时附件？

## Phase 0 调研要求

- 把 SPEC 中的需求逐项映射到 Agent 基座、Skill、CLI、Python、专用模型、人工审核和飞书，确认每一步由谁执行、产物保存在哪里。
- 验证“对话驱动 → Skill 编排 → CLI 执行 → 结构化返回 → 最终写入”这条运行主线，并明确每一层允许做什么、禁止做什么。
- 定义不同 Agent 基座都可以使用的 CLI 契约，列出命令、参数、返回结果、错误和状态校验规则，并给出审核队列的格式化展示与用户决定格式。
- 定义需要由 Python 强制执行的数据约束、最终写入条件和审核规则，不能把这些限制只写进 Skill。
- 验证任务只在全部处理完成后保存最终结果，不生成持久操作 ID、中间状态、恢复位置或断点记录。
- 给出 Agent 基座主控下的典型调用时序，至少覆盖资料接收、知识演化和人工审核。
- 确认 Codex 与 Hermes 在开发测试中读取 Skill、调用 CLI 和提供权限的方式，保证业务核心不依赖某个基座的内部实现。
- 核对飞书文档、知识库和多维表格的 API、授权范围、调用限额和事件机制。
- 区分可以直接满足、需要额外开发和暂时无法满足的部分。
- 对初步建议逐项给出采用、调整或放弃的结论，并在 `research.md` 中记录决定、理由和考虑过的替代方案。
- 检查源码 Skill、CLI 和 Python 模块能否在 Codex 与 Hermes 测试环境中共同工作，避免只规划 Python 内部模块而遗漏 Skill 和基座适配。
- 如果飞书的某项能力存在关键缺口，记录缺口和可行处理方式，交给用户确认，不要直接把飞书从技术方向中移除。

## 本次 Plan 的输出边界

- 本次只生成 Plan 及 Phase 0、Phase 1 的设计产物。
- 不生成 `tasks.md`，也不开始实现。
- 不设计或生成安装包；发布与打包另行规划。